docs: backporting

CONTRIBUTING.md

@@ -250,20 +250,12 @@ confused with 3-letter acronyms.
 
 ## Design Proposals
 
-Solana's architecture is described by docs generated from markdown files in
-the `docs/src/` directory, maintained by an *editor* (currently @garious). To
-add a design proposal, you'll need to include it in the
-[Accepted Design Proposals](https://docs.solana.com/proposals/accepted-design-proposals)
-section of the Solana docs.  Here's the full process:
-
-1. Propose a design by creating a PR that adds a markdown document to the
-   `docs/src/proposals` directory and references it from the [table of
-   contents](docs/src/SUMMARY.md). Add any relevant *maintainers* to the PR
-   review.
-2. The PR being merged indicates your proposed change was accepted and that the
-   maintainers support your plan of attack.
-3. Submit PRs that implement the proposal. When the implementation reveals the
-   need for tweaks to the proposal, be sure to update the proposal and have that
-   change reviewed by the same people as in step 1.
-4. Once the implementation is complete, submit a PR that moves the link from
-   the Accepted Proposals to the Implemented Proposals section.
+Solana's architecture is described by docs generated from markdown files in the `docs/src/`
+directory and viewable on the official [Solana Documentation](https://docs.solana.com) website.
+
+Current design proposals may be viewed on the docs site:
+
+1. [Accepted Proposals](https://docs.solana.com/proposals/accepted-design-proposals.md).
+2. [Implemented Proposals](https://docs.solana.com/implemented-proposals/implemented-proposals.md)
+
+New design proposals should follow this guide on [how to submit a design proposal](./docs/src/proposals.md#submit-a-design-proposal).

docs/components/Card.jsx

@@ -0,0 +1,50 @@
+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, externalIcon = false }) {
+  /*
+  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>
+            {externalIcon && (
+              <svg
+                width="13.5"
+                height="13.5"
+                aria-hidden="true"
+                viewBox="0 0 24 24"
+                className={styles.iconExternalIcon}
+              >
+                <path
+                  fill="currentColor"
+                  d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"
+                ></path>
+              </svg>
+            )}
+          </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

@@ -53,42 +53,62 @@ module.exports = {
       },
       items: [
         {
-          href: "https://spl.solana.com",
-          label: "Program Library »",
+          to: "introduction",
+          label: "Learn",
           position: "left",
         },
         {
-          to: "developing/programming-model/overview",
-          label: "Develop",
+          to: "cluster/overview",
+          label: "Architecture",
           position: "left",
         },
         {
-          to: "running-validator",
-          label: "Validate",
+          to: "cli",
+          label: "CLI",
           position: "left",
         },
         {
-          to: "integrations/exchange",
-          label: "Integrate",
+          to: "/developers",
+          label: "Developers",
           position: "left",
         },
         {
-          to: "cluster/overview",
-          label: "Learn",
+          to: "running-validator",
+          label: "Validators",
+          position: "left",
+        },
+        {
+          label: "More",
           position: "left",
+          items: [
+            { label: "Terminology", to: "terminology" },
+            { label: "Staking", to: "staking" },
+            { label: "Integrations", to: "integrations/exchange" },
+            { label: "Economics", to: "economics_overview" },
+            { label: "Proposals", to: "proposals" },
+            {
+              href: "https://spl.solana.com",
+              label: "Solana Program Library »",
+              position: "left",
+            },
+          ],
         },
         {
           type: "localeDropdown",
           position: "right",
         },
         {
           href: "https://discordapp.com/invite/pquxPsq",
-          label: "Chat",
+          // label: "Discord",
+          className: "header-link-icon header-discord-link",
+          "aria-label": "Solana Discord",
           position: "right",
         },
         {
           href: "https://github.com/solana-labs/solana",
-          label: "GitHub",
+          // label: "GitHub",
+          className: "header-link-icon header-github-link",
+          "aria-label": "GitHub repository",
           position: "right",
         },
       ],
@@ -103,37 +123,69 @@ module.exports = {
       style: "dark",
       links: [
         {
-          title: "Docs",
+          title: "Documentation",
           items: [
             {
-              label: "Introduction",
+              label: "Learn",
               to: "introduction",
             },
+            {
+              label: "Developers",
+              to: "/developers",
+            },
+            {
+              label: "Validators",
+              to: "running-validator",
+            },
+            {
+              label: "Command Line",
+              to: "cli",
+            },
+            {
+              label: "Architecture",
+              to: "cluster/overview",
+            },
           ],
         },
         {
           title: "Community",
           items: [
             {
-              label: "Discord",
+              label: "Stack Exchange »",
+              href: "https://solana.stackexchange.com/",
+            },
+            {
+              label: "GitHub »",
+              href: "https://github.com/solana-labs/solana",
+            },
+            {
+              label: "Discord »",
               href: "https://discordapp.com/invite/pquxPsq",
             },
             {
-              label: "Twitter",
+              label: "Twitter »",
               href: "https://twitter.com/solana",
             },
             {
-              label: "Forums",
+              label: "Forums »",
               href: "https://forums.solana.com",
             },
           ],
         },
         {
-          title: "More",
+          title: "Resources",
           items: [
             {
-              label: "GitHub",
-              href: "https://github.com/solana-labs/solana",
+              label: "Proposals",
+              to: "proposals",
+            },
+            {
+              label: "Integrations",
+              to: "integrations/exchange",
+            },
+            {
+              href: "https://spl.solana.com",
+              label: "Solana Program Library »",
             },
           ],
         },

docs/layouts/CardLayout.js

@@ -0,0 +1,87 @@
+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]);
+        sidebarItems[key].collapsed = true;
+      } 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;
+  }
+
+  // fix for local routing that does not specify starting at the site root
+  if (
+    !(
+      item?.href.startsWith("/") ||
+      item?.href.startsWith("http:") ||
+      item?.href.startsWith("https")
+    )
+  )
+    item.href = `/${item?.href}`;
+
+  return item;
+};

docs/publish-docs.sh

@@ -30,21 +30,22 @@ cat > "$CONFIG_FILE" <<EOF
   "name": "$PROJECT_NAME",
   "scope": "solana-labs",
   "redirects": [
-    { "source": "/apps", "destination": "/developing/programming-model/overview" },
-    { "source": "/apps/bakcwards-compatibility", "destination": "/developing/backwards-compatibility" },
+    { "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/builtin-programs" },
+    { "source": "/apps/builtins", "destination": "/developing/runtime-facilities/programs" },
     { "source": "/apps/drones", "destination": "/developing/on-chain-programs/examples" },
     { "source": "/apps/hello-world", "destination": "/developing/on-chain-programs/examples" },
     { "source": "/apps/javascript-api", "destination": "/developing/clients/javascript-api" },
     { "source": "/apps/jsonrpc-api", "destination": "/developing/clients/jsonrpc-api" },
     { "source": "/apps/programming-faq", "destination": "/developing/on-chain-programs/faq" },
-    { "source": "/apps/rent", "destination": "/developing/programming-model/accounts" },
-    { "source": "/apps/sysvars", "destination": "/developing/programming-model/sysvars" },
-    { "source": "/apps/webwallet", "destination": "/developing/on-chain-programs/examples" },
-    { "source": "/implemented-proposals/cross-program-invocation", "destination": "/developing/programming-model/cpi" },
-    { "source": "/implemented-proposals/program-derived-addresses", "destination": "/developing/programming-model/program-derived-addresses" },
-    { "source": "/implemented-proposals/secp256k1_instruction", "destination": "/developing/programming-model/secpk1-instructions" }
+    { "source": "/apps/rent", "destination": "/developing/programming-model/accounts#rent" },
+    { "source": "/apps/sysvars", "destination": "/developing/runtime-facilities/sysvars" },
+    { "source": "/apps/webwallet", "destination": "/wallet-guide" },
+    { "source": "/implemented-proposals/cross-program-invocation", "destination": "/developing/programming-model/calling-between-programs" },
+    { "source": "/implemented-proposals/program-derived-addresses", "destination": "/developing/programming-model/calling-between-programs#program-derived-addresses" },
+    { "source": "/implemented-proposals/secp256k1_instruction", "destination": "/developing/runtime-facilities/programs#secp256k1-program" }
   ]
 }
 EOF