[docs] developers home page (#27436)

* feat: developers landing page

* fix: updated links

* fix: updated labels for translateIds

* refactor: updated index page to use Card component

* style: removed whitespace

* refactor: added static labels for developer sidebar items

* feat: developer's sidebar and new layout file

* chore: removed whitespace

* fix: removed duplicate CLI sidebar item

* fix: card shadows and RPC card text

docs/components/Card.jsx

@@ -0,0 +1,36 @@
+import React from "react";
+import clsx from "clsx";
+import Link from "@docusaurus/Link";
+import styles from "../src/pages/styles.module.css";
+import Translate from "@docusaurus/Translate";
+
+function Card({ to, header, body }) {
+  /*
+  Both the `header` and `body` expect an object with the following type
+  header = {
+    label: String, //
+    translateId: String //
+  }
+  */
+
+  return (
+    <div className={clsx("col col--4 ", styles.feature)}>
+      <Link className="navbar__link card" to={to}>
+        <div className="card__header">
+          <h3>
+            <Translate description={header.translateId}>
+              {header.label}
+            </Translate>
+          </h3>
+        </div>
+        <div className="card__body">
+          <p>
+            <Translate description={body.translateId}>{body.label}</Translate>
+          </p>
+        </div>
+      </Link>
+    </div>
+  );
+}
+
+export default Card;

docs/docusaurus.config.js

@@ -68,7 +68,7 @@ module.exports = {
           position: "left",
         },
         {
-          to: "developing/programming-model/overview",
+          to: "/developers",
           label: "Developers",
           position: "left",
         },
@@ -131,7 +131,7 @@ module.exports = {
             },
             {
               label: "Developers",
-              to: "developing/programming-model/overview",
+              to: "/developers",
             },
             {
               label: "Validators",

docs/layouts/CardLayout.js

@@ -0,0 +1,75 @@
+import React from "react";
+import Layout from "@theme/Layout";
+import DocSidebar from "@theme/DocSidebar";
+import ThemeClassNames from "@docusaurus/theme-classic/lib/theme/DocPage/styles.module.css";
+import sidebar from "../sidebars";
+
+function CardLayout({
+  children,
+  sidebarKey = false,
+  title = "",
+  description = "",
+  path = "",
+}) {
+  // load the sidebar item from the master `sidebars.js` file
+  const sidebarItems = (sidebarKey && sidebar?.[sidebarKey]) || [];
+
+  // process each of the loaded sidebar items for formatting
+  if (sidebarItems?.length) {
+    Object.keys(sidebarItems).forEach((key) => {
+      if (sidebarItems[key]?.type?.toLowerCase() === "category") {
+        for (let i = 0; i < sidebarItems[key]?.items?.length; i++)
+          sidebarItems[key].items[i] = formatter(sidebarItems[key].items[i]);
+      } else sidebarItems[key] = formatter(sidebarItems[key]);
+    });
+  }
+
+  // return the page layout, ready to go
+  return (
+    <Layout title={title} description={description}>
+      <div className={ThemeClassNames.docPage}>
+        {sidebarItems?.length > 0 && (
+          <aside className={ThemeClassNames.docSidebarContainer}>
+            <DocSidebar sidebar={sidebarItems} path={path}></DocSidebar>
+          </aside>
+        )}
+
+        <main className={ThemeClassNames.docPage}>{children}</main>
+      </div>
+    </Layout>
+  );
+}
+export default CardLayout;
+
+/*
+  Create a simple label based on the string of a doc file path
+*/
+const computeLabel = (label) => {
+  label = label.split("/");
+  label = label[label?.length - 1]?.replace("-", " ");
+  label = label.charAt(0).toUpperCase() + label.slice(1);
+  return label && label;
+};
+
+/*
+  Parser to format a sidebar item to be compatible with the `DocSidebar` component
+*/
+const formatter = (item) => {
+  // handle string only document ids
+  if (typeof item === "string") {
+    item = {
+      type: "link",
+      href: item,
+      label: computeLabel(item) || item || "[unknown label]",
+    };
+  }
+  // handle object style docs
+  else if (item?.type?.toLowerCase() === "doc") {
+    item.type = "link";
+    item.href = item.id;
+    item.label = item.label || computeLabel(item.href) || "[unknown label]";
+    delete item.id;
+  }
+
+  return item;
+};

docs/publish-docs.sh

@@ -30,7 +30,8 @@ cat > "$CONFIG_FILE" <<EOF
   "name": "$PROJECT_NAME",
   "scope": "solana-labs",
   "redirects": [
-    { "source": "/apps", "destination": "/developing/programming-model/overview" },
+    { "source": "/apps", "destination": "/developers" },
+    { "source": "/developing/programming-model/overview", "destination": "/developers" },
     { "source": "/apps/backwards-compatibility", "destination": "/developing/backwards-compatibility" },
     { "source": "/apps/break", "destination": "/developing/on-chain-programs/examples" },
     { "source": "/apps/builtins", "destination": "/developing/runtime-facilities/programs" },

docs/sidebars.js

@@ -48,9 +48,9 @@ module.exports = {
       items: [
         "terminology",
         {
-          type: "ref",
+          type: "link",
+          href: "/developers",
           label: "Developers",
-          id: "developing/programming-model/overview",
         },
         {
           type: "ref",
@@ -75,45 +75,100 @@ module.exports = {
       ],
     },
   ],
-  developingSidebar: [
+  developerSidebar: [
     {
-      type: "doc",
+      type: "link",
-      id: "developing/programming-model/overview",
+      href: "/developers",
       label: "Overview",
     },
     {
       type: "category",
       label: "Getting Started",
-      items: ["developing/intro/programs", "developing/intro/rent"],
+      items: [
+        {
+          type: "doc",
+          id: "developing/intro/programs",
+          label: "What are Programs?",
+        },
+        {
+          type: "doc",
+          id: "developing/intro/rent",
+          label: "What is Rent?",
+        },
+      ],
     },
     {
       type: "category",
       label: "Core Concepts",
       // collapsed: false,
       items: [
-        "developing/programming-model/transactions",
+        {
-        "developing/programming-model/accounts",
+          type: "doc",
-        "developing/programming-model/calling-between-programs",
+          id: "developing/programming-model/transactions",
-        "developing/programming-model/runtime",
+          label: "Transactions",
+        },
+        {
+          type: "doc",
+          id: "developing/programming-model/accounts",
+          label: "Accounts",
+        },
+        {
+          type: "doc",
+          id: "developing/programming-model/calling-between-programs",
+          label: "Calling between programs",
+        },
+        {
+          type: "doc",
+          id: "developing/programming-model/runtime",
+          label: "Runtime",
+        },
       ],
     },
     {
       type: "category",
       label: "Clients",
       items: [
-        "developing/clients/jsonrpc-api",
+        {
-        "developing/clients/javascript-api",
+          type: "doc",
-        "developing/clients/javascript-reference",
+          id: "developing/clients/jsonrpc-api",
-        "developing/clients/rust-api",
+          label: "JSON RPC API",
+        },
+        {
+          type: "doc",
+          id: "developing/clients/javascript-api",
+          label: "Web3 JavaScript API",
+        },
+        {
+          type: "doc",
+          id: "developing/clients/javascript-reference",
+          label: "Web3 API Reference",
+        },
+        {
+          type: "doc",
+          id: "developing/clients/rust-api",
+          label: "Rust API",
+        },
       ],
     },
     {
       type: "category",
       label: "Writing Programs",
       items: [
-        "developing/on-chain-programs/overview",
+        {
-        "developing/on-chain-programs/developing-rust",
+          type: "doc",
-        "developing/on-chain-programs/developing-c",
+          id: "developing/on-chain-programs/overview",
+          label: "Overview",
+        },
+        {
+          type: "doc",
+          id: "developing/on-chain-programs/developing-rust",
+          label: "Developing with Rust",
+        },
+        {
+          type: "doc",
+          id: "developing/on-chain-programs/developing-c",
+          label: "Developing with C/C++",
+        },
         {
           type: "doc",
           label: "Deploying",
@@ -124,8 +179,16 @@ module.exports = {
           label: "Debugging",
           id: "developing/on-chain-programs/debugging",
         },
-        "developing/on-chain-programs/examples",
+        {
-        "developing/on-chain-programs/faq",
+          type: "doc",
+          id: "developing/on-chain-programs/examples",
+          label: "Program Examples",
+        },
+        {
+          type: "doc",
+          id: "developing/on-chain-programs/faq",
+          label: "FAQ",
+        },
       ],
     },
     {
@@ -137,16 +200,30 @@ module.exports = {
           label: "Overview",
           id: "developing/runtime-facilities/programs",
         },
-        "developing/runtime-facilities/sysvars",
+        {
+          type: "doc",
+          id: "developing/runtime-facilities/sysvars",
+          label: "Sysvar Cluster Data",
+        },
       ],
     },
     {
       type: "category",
       label: "Local Development",
       collapsed: false,
-      items: ["developing/test-validator"],
+      items: [
+        {
+          type: "doc",
+          id: "developing/test-validator",
+          label: "Solana Test Validator",
+        },
+      ],
+    },
+    {
+      type: "doc",
+      id: "developing/backwards-compatibility",
+      label: "Backward Compatibility Policy",
     },
-    "developing/backwards-compatibility",
   ],
   validatorsSidebar: [
     "running-validator",
@@ -180,7 +257,6 @@ module.exports = {
   cliSidebar: [
     "cli",
     "cli/install-solana-cli-tools",
-    "cli/install-solana-cli-tools",
     {
       type: "category",
       label: "Command-line Wallets",

docs/src/cli/deploy-a-program.md

@@ -6,7 +6,7 @@ Developers can deploy on-chain [programs](terminology.md#program) (often called
 smart contracts elsewhere) with the Solana tools.
 
 To learn about developing and executing programs on Solana, start with the
-[overview](developing/programming-model/overview.md) and then dig into the
+[intro to Solana programs](developing/intro/programs.md) and then dig into the
 details of [on-chain programs](developing/on-chain-programs/overview.md).
 
 To deploy a program, use the Solana tools to interact with the on-chain loader

docs/src/css/custom.css

@@ -27,10 +27,10 @@
 }
 
 @keyframes fadeInUp {
-  0% {
+  /* 0% {
     opacity: 0;
     transform: translateY(1.5rem);
-  }
+  } */
 }
 
 main {
@@ -44,6 +44,14 @@ main {
   padding: 0 var(--ifm-pre-padding);
 }
 
+.cards__container {
+  margin: 3em 0;
+}
+
+.cards__container .col {
+  margin-bottom: 1em;
+}
+
 .card {
   padding: 1rem;
   margin-top: 0rem;
@@ -51,7 +59,9 @@ main {
   animation-delay: 150ms;
   transition-property: all;
   transition-duration: 200ms;
-  box-shadow: 0 8px 28px 4px rgba(86, 91, 115, 0.15);
+  align-items: start;
+  height: 100%;
+  box-shadow: 0 8px 15px 2px rgba(86, 91, 115, 0.1);
 }
 
 .card a {

docs/src/pages/developers.js

@@ -0,0 +1,168 @@
+import React from "react";
+import styles from "./styles.module.css";
+import Card from "../../components/Card";
+import CardLayout from "../../layouts/CardLayout";
+
+function Developers() {
+  return (
+    <CardLayout
+      sidebarKey="developerSidebar"
+      title="Developers"
+      description="Solana Documentation"
+      path="/developers"
+    >
+      <section className={styles.features}>
+        <div className="container">
+          <section className="">
+            <h2>Learn Solana development</h2>
+
+            <div className="row cards__container">
+              <Card
+                to="developing/intro/programs"
+                header={{
+                  label: "Getting Started",
+                  translateId: "developer-programs",
+                }}
+                body={{
+                  label: "Discover what Solana programs are and how they work.",
+                  translateId: "learn-programs",
+                }}
+              />
+
+              <Card
+                to="developing/programming-model/transactions"
+                header={{
+                  label: "Transactions",
+                  translateId: "developer-transactions",
+                }}
+                body={{
+                  label:
+                    "Program execution begins with a transaction being submitted to the cluster.",
+                  translateId: "learn-transactions",
+                }}
+              />
+
+              <Card
+                to="developing/programming-model/accounts"
+                header={{
+                  label: "Accounts",
+                  translateId: "developer-accounts",
+                }}
+                body={{
+                  label:
+                    "Understand how programs store data or state on the Solana blockchain.",
+                  translateId: "learn-accounts",
+                }}
+              />
+            </div>
+          </section>
+
+          <section className="">
+            <h2>Learn through coding</h2>
+
+            <div className="row cards__container">
+              <Card
+                to="developing/on-chain-programs/overview"
+                header={{
+                  label: "Building Programs",
+                  translateId: "start-building",
+                }}
+                body={{
+                  label:
+                    "Start developing on-chain Solana programs with Rust or C/C++.",
+                  translateId: "start-building",
+                }}
+              />
+
+              <Card
+                to="developing/on-chain-programs/examples#helloworld"
+                header={{
+                  label: "Hello World Example",
+                  translateId: "developer-hello-world",
+                }}
+                body={{
+                  label:
+                    "Example of how to use code to interact with the Solana blockchain.",
+                  translateId: "learn-hello-world",
+                }}
+              />
+
+              <Card
+                to="developing/on-chain-programs/examples"
+                header={{
+                  label: "Example Programs",
+                  translateId: "developer-examples",
+                }}
+                body={{
+                  label:
+                    "Browse and clone working example programs from GitHub.",
+                  translateId: "learn-by-example",
+                }}
+              />
+            </div>
+          </section>
+
+          <section className="">
+            <h2>Setup your local development</h2>
+
+            <div className="row cards__container">
+              <Card
+                to="developing/test-validator"
+                header={{
+                  label: "Solana Test Validator",
+                  translateId: "developer-test-validator",
+                }}
+                body={{
+                  label:
+                    "Quickly setup and run a self contained local Solana blockchain for faster development.",
+                  translateId: "learn-test-validator",
+                }}
+              />
+
+              <Card
+                to="developing/clients/jsonrpc-api"
+                header={{
+                  label: "RPC API",
+                  translateId: "rpc-api",
+                }}
+                body={{
+                  label:
+                    "Interact with the Solana clusters via the JSON RPC API.",
+                  translateId: "rpc-api-info",
+                }}
+              />
+              {/* future card to replace the RPC API card */}
+              {/* <Card
+                to="developing/tools"
+                header={{
+                  label: "Essential Tools",
+                  translateId: "developer-tools",
+                }}
+                body={{
+                  label:
+                    "Explore the essential developer tools for building and deploying Solana programs.",
+                  translateId: "explore-tools",
+                }}
+              /> */}
+
+              <Card
+                to="developing/on-chain-programs/debugging"
+                header={{
+                  label: "Debugging Programs",
+                  translateId: "developer-debugging",
+                }}
+                body={{
+                  label:
+                    "Understand using unit test, logging. and error handling programs.",
+                  translateId: "learn-debugging",
+                }}
+              />
+            </div>
+          </section>
+        </div>
+      </section>
+    </CardLayout>
+  );
+}
+
+export default Developers;

docs/src/pages/index.js

@@ -1,154 +1,96 @@
 import React from "react";
-import clsx from "clsx";
 import Layout from "@theme/Layout";
-import Link from "@docusaurus/Link";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
-// import useBaseUrl from "@docusaurus/useBaseUrl";
 import styles from "./styles.module.css";
-import Translate from "@docusaurus/Translate";
+import Card from "../../components/Card";
-// import { translate } from "@docusaurus/Translate";
 
 function Home() {
   const context = useDocusaurusContext();
   const { siteConfig = {} } = context;
+
   return (
     <Layout title="Homepage" description="Solana Documentation">
       <main>
         <section className={styles.features}>
           <div className="container">
             <div className="row cards__container">
-              <div className={clsx("col col--4", styles.feature)}>
+              <Card
-                <Link
+                to="developers"
-                  className="navbar__link"
+                header={{
-                  to="developing/programming-model/overview"
+                  label: "⛏ Start Developing",
-                >
+                  translateId: "start-building",
-                  <div className="card">
+                }}
-                    <div className="card__header">
+                body={{
-                      <h3>
+                  label:
-                        <Translate description="start-building">
+                    "Get started building your decentralized app or marketplace with Solana.",
-                          ⛏ Start Developing
+                  translateId: "get-started-building",
-                        </Translate>
+                }}
-                      </h3>
+              />
-                    </div>
+
-                    <div className="card__body">
+              <Card
-                      <p>
+                to="running-validator"
-                        <Translate description="get-started-building">
+                header={{
-                          Get started building your decentralized app or
+                  label: "🎛 Run a Validator Node",
-                          marketplace with Solana.
+                  translateId: "run-validator",
-                        </Translate>
+                }}
-                      </p>
+                body={{
-                    </div>
+                  label:
-                  </div>
+                    "Validate transactions, secure the network, and earn rewards.",
-                </Link>
+                  translateId: "validate-transactions",
-              </div>
+                }}
-              <div className={clsx("col col--4", styles.feature)}>
+              />
-                <Link className="navbar__link" to="running-validator">
+
-                  <div className="card">
+              <Card
-                    <div className="card__header">
+                to="https://spl.solana.com/token"
-                      <h3>
+                header={{
-                        <Translate description="run-validator">
+                  label: "🏛 Create an SPL Token",
-                          🎛 Run a Validator Node
+                  translateId: "create-spl",
-                        </Translate>
+                }}
-                      </h3>
+                body={{
-                    </div>
+                  label:
-                    <div className="card__body">
+                    "Launch your own SPL Token, Solana's equivalent of ERC-20.",
-                      <p>
+                  translateId: "erc-20",
-                        <Translate description="validate-transactions">
+                }}
-                          Validate transactions, secure the network, and earn
+              />
-                          rewards.
+
-                        </Translate>
+              <Card
-                      </p>
+                to="integrations/exchange"
-                    </div>
+                header={{
-                  </div>
+                  label: "🏦 Integrate an Exchange",
-                </Link>
+                  translateId: "integrate-exchange",
-              </div>
+                }}
-              <div className={clsx("col col--4", styles.feature)}>
+                body={{
-                <Link
+                  label:
-                  className="navbar__link"
+                    "Follow our extensive integration guide to ensure a seamless user experience.",
-                  to="https://spl.solana.com/token"
+                  translateId: "integration-guide",
-                >
+                }}
-                  <div className="card">
+              />
-                    <div className="card__header">
+
-                      <h3>
+              <Card
-                        <Translate description="create-spl">
+                to="wallet-guide"
-                          🏛 Create an SPL Token
+                header={{
-                        </Translate>
+                  label: "📲 Manage a Wallet",
-                      </h3>
+                  translateId: "manage-wallet",
-                    </div>
+                }}
-                    <div className="card__body">
+                body={{
-                      <p>
+                  label:
-                        <Translate description="erc-20">
+                    "Create a wallet, check your balance, and learn about wallet options.",
-                          Launch your own SPL Token, Solana's equivalent of
+                  translateId: "wallet-options",
-                          ERC-20.
+                }}
-                        </Translate>
+              />
-                      </p>
+
-                    </div>
+              <Card
-                  </div>
+                to="introduction"
-                </Link>
+                header={{
-              </div>
+                  label: "🤯 Learn How Solana Works",
-              <div className={clsx("col col--4", styles.feature)}>
+                  translateId: "learn-how",
-                <Link className="navbar__link" to="integrations/exchange">
+                }}
-                  <div className="card">
+                body={{
-                    <div className="card__header">
+                  label:
-                      <h3>
+                    "Get a high-level understanding of Solana's architecture.",
-                        <Translate description="integrate-exchange">
+                  translateId: "high-level",
-                          🏦 Integrate an Exchange
+                }}
-                        </Translate>
+              />
-                      </h3>
-                    </div>
-                    <div className="card__body">
-                      <p>
-                        <Translate description="integration-guide">
-                          Follow our extensive integration guide to ensure a
-                          seamless user experience.
-                        </Translate>
-                      </p>
-                    </div>
-                  </div>
-                </Link>
-              </div>
-              <div className={clsx("col col--4", styles.feature)}>
-                <Link className="navbar__link" to="wallet-guide">
-                  <div className="card">
-                    <div className="card__header">
-                      <h3>
-                        <Translate description="manage-wallet">
-                          📲 Manage a Wallet
-                        </Translate>
-                      </h3>
-                    </div>
-                    <div className="card__body">
-                      <p>
-                        <Translate description="wallet-options">
-                          Create a wallet, check your balance, and learn about
-                          wallet options.
-                        </Translate>
-                      </p>
-                    </div>
-                  </div>
-                </Link>
-              </div>
-              <div className={clsx("col col--4", styles.feature)}>
-                <Link className="navbar__link" to="introduction">
-                  <div className="card">
-                    <div className="card__header">
-                      <h3>
-                        <Translate description="learn-how">
-                          🤯 Learn How Solana Works
-                        </Translate>
-                      </h3>
-                    </div>
-                    <div className="card__body">
-                      <p>
-                        <Translate description="high-level">
-                          Get a high-level understanding of Solana's
-                          architecture.
-                        </Translate>
-                      </p>
-                    </div>
-                  </div>
-                </Link>
-              </div>
             </div>
           </div>
         </section>