docs: add/update documentation (#38590)

CONTRIBUTING.md

@@ -1,7 +1,3 @@
-> ### All our documentation and contributing guidlines are available on a dedicated site here: <https://contribute.freecodecamp.org>.
+## Our contributing docs are available here: <https://contribute.freecodecamp.org>.
 
-### Looking to edit the contributing guidelines?
+Looking to edit these docs? Read [this document](https://contribute.freecodecamp.org/#/how-to-work-on-the-docs-theme) first.
-
-To work on the contributing guidelines, you can edit these files [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/docs). When your changes are merged, it will be made available automatically at the documentation site linked above.
-
-**You do not need to setup anything locally for working on the documentation.**

docs/README.md

@@ -1,37 +1,3 @@
-> ### All our documentation and contributing guidlines are available on a dedicated site here: <https://contribute.freecodecamp.org>.
+## Our contributing docs are available here: <https://contribute.freecodecamp.org>.
 
-### Looking to edit the contributing guidelines?
+Looking to edit these docs? Read [this document](https://contribute.freecodecamp.org/#/how-to-work-on-the-docs-theme) first.
-
-To work on the contributing guidelines, you can edit these files [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/docs). When your changes are merged, it will be made available automatically at the documentation site linked above.
-
-**You do not need to setup anything locally for working on the documentation.**
-
-### How is the documentation site generated?
-
-The documentation site is generated using [`docsify`](https://docsify.js.org), and served using GitHub pages. Typically you would not need to change any configuration, or build the site locally, but incase you are interested here is how it works:
-
-1. The guideline homepage's source is [`index.html`](index.html). GitHub Pages serve this file as a SPA using `docsify`.
-2. The `docsify` script generates the content of `markdown` files in `/docs` directory on demand when you are browsing the documentation site.
-3. The home page is genrated from the [`index.md`](index.md) and sidebar navigation is generated from [`components/sidebar.md`](components/sidebar.md).
-4. To serve the docs locally:
-
-    Clone freeCodeCamp:
-
-    ```sh
-    git clone https://github.com/freeCodeCamp/freeCodeCamp.git
-    docsify serve docs
-    ```
-
-    Install `docsify`:
-
-    ```sh
-    npm install -g docsify
-    ```
-
-    and serve the `/docs` directory
-
-    ```sh
-    docsify serve docs
-    ```
-
-    Alternatively, if you have installed freeCodeCamp locally (see the local setup guide), we bundle the CLI with the development tools so you can run `npm run docs:serve` from the root of the repo.

docs/components/sidebar.md

@@ -4,12 +4,14 @@
 - [How to work on coding challenges](/how-to-work-on-coding-challenges)
 - [How to setup freeCodeCamp locally](/how-to-setup-freecodecamp-locally)
 - [How to open a pull request](/how-to-open-a-pull-request)
+- [How to work on the news theme](/how-to-work-on-the-news-theme)
+- [How to work on the docs theme](/how-to-work-on-the-docs-theme)
 - **DevOps Guides**
 - [Overview and Workflows](/devops.md)
-- [Flight Manual: 01 - List Azure Virtual Machines](/flight-manuals/01-getting-list-of-virtual-machines.md)
+- **Flight Manuals (for Staff & Mods)**
-- [Flight Manual: 02 - Provision API Instances](/flight-manuals/02-spinning-api-instances.md)
+- [01 - List Virtual Machines](/flight-manuals/01-getting-list-of-virtual-machines.md)
-<!-- Prevent going to next section-->
+- [02 - Provision API Instances](/flight-manuals/02-spinning-api-instances.md)
-- []()
+- [02 - Using Reply Templates](/flight-manuals/03-using-reply-templates.md)
 ----
 - **Community**
 - [GitHub Repository](https://github.com/freecodecamp/freecodecamp)

docs/flight-manuals/01-getting-list-of-virtual-machines.md

@@ -1,14 +1,18 @@
-### Getting a list of the VMs from Azure
+# Getting a list of the Virtual Machines
+
+You can get a list of virtual machines from the below vendors only if you have been given access. You may need to list a VM and its public IP for getting SSH access and doing maintenance.
+
+## Azure
 
 Install Azure CLI `az`: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli
 
-> (onetime) Install on macOS with [`homebrew`](https://brew.sh):
+> **(One-time) Install on macOS with [`homebrew`](https://brew.sh):**
 
 ```
 brew install azure-cli
 ```
 
-> (onetime) Login:
+> **(One-time) Login:**
 
 ```
 az login
@@ -20,17 +24,17 @@ az login
 az vm list-ip-addresses --output table
 ```
 
-### Getting a list of the VMs from Digital Ocean
+## Digital Ocean
 
 Install Digital Ocean CLI `doctl`: https://github.com/digitalocean/doctl#installing-doctl
 
-> (onetime) Install on macOS with [`homebrew`](https://brew.sh):
+> **(One-time) Install on macOS with [`homebrew`](https://brew.sh):**
 
 ```
 brew install doctl
 ```
 
-> (onetime) Login:
+> **(One-time) Login:**
 
 Authentication and context switching: https://github.com/digitalocean/doctl#authenticating-with-digitalocean
 

docs/flight-manuals/03-using-reply-templates.md

@@ -1,4 +1,4 @@
-# Reviewing Pull Requests
+# Using Reply Templates
 
 These are some of the standard reply templates that you may use while reviewing pull requests and triaging issues.
 

docs/how-to-work-on-the-docs-theme.md

@@ -0,0 +1,43 @@
+# How to work on the docs theme
+
+> [!NOTE]
+> **You do not need to setup anything locally for working on the documentation content.**
+>
+> To work on the contributing guidelines, you can edit or add files in the `docs` directory [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/docs). When your changes are merged, it will be made available automatically at the documentation site.
+
+## About the documentation site
+
+While you do not need to generate the documenatation site locally, sometimes it may be required for instance if you are working on the site theme or a feature for the site.
+
+The site is generated using [`docsify`](https://docsify.js.org), and served using GitHub pages.
+
+Typically you would not need to change any configuration, or build the site locally, but incase you are interested here is how it works:
+
+- The homepage's source for this site is available in [`docs/index.html`](index.html).
+- We serve this file as a SPA using `docsify` and GitHub Pages.
+- The `docsify` script generates the content of `markdown` files in `docs` directory on demand.
+- The homepage is generated from the [`index.md`](index.md).
+- the sidebar navigation is generated from [`components/sidebar.md`](components/sidebar.md).
+
+## Serving the documenation site locally
+
+Clone freeCodeCamp:
+
+```sh
+git clone https://github.com/freeCodeCamp/freeCodeCamp.git
+docsify serve docs
+```
+
+Install `docsify`:
+
+```sh
+npm install -g docsify
+```
+
+and serve the `/docs` directory
+
+```sh
+docsify serve docs
+```
+
+Alternatively, if you have installed freeCodeCamp locally (see the local setup guide), we bundle the CLI with the development tools so you can run `npm run docs:serve` from the root of the repo.

docs/how-to-work-on-the-news-theme.md

@@ -0,0 +1,9 @@
+<!--
+
+The source for this document is available at:
+https://github.com/freeCodeCamp/news-theme/blob/master/CONTRIBUTING.md
+
+Please edit that file instead.
+
+-->
+[remote-markdown-url](https://raw.githubusercontent.com/freeCodeCamp/news-theme/master/CONTRIBUTING.md)

docs/index.html

@@ -9,35 +9,20 @@
   <meta name="description" content="Description">
   <meta name="viewport"
     content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
-<!--social-->
+  <!--social-->
-<meta content='freeCodeCamp.org' name='og:title' />
+  <meta content='freeCodeCamp.org' name='og:title' />
-<meta
+  <meta content={ 'Learn to code. Build projects. Earn certifications.'
-  content={
+    + 'Since 2015, 40,000 graduates have gotten jobs at tech '
-    'Learn to code. Build projects. Earn certifications.' +
+    + 'companies including Google, Apple, Amazon, and Microsoft.' } name='og:description' />
-    'Since 2015, 40,000 graduates have gotten jobs at tech ' +
+  <meta content='https://cdn.freecodecamp.org/platform/universal/fcc-og-1200-social-green.png' property='og:image' />
-    'companies including Google, Apple, Amazon, and Microsoft.'
-  }
-  name='og:description'
-/>
-<meta
-  content='https://cdn.freecodecamp.org/platform/universal/fcc-og-1200-social-green.png'
-  property='og:image'
-/>
 
-<meta content='summary_large_image' key='twitter:card' name='twitter:card' />
+  <meta content='summary_large_image' key='twitter:card' name='twitter:card' />
-<meta
+  <meta content='https://cdn.freecodecamp.org/platform/universal/fcc-twitter-1120X600-social-green.png'
-  content='https://cdn.freecodecamp.org/platform/universal/fcc-twitter-1120X600-social-green.png'
+    name='twitter:image:src' />
-  name='twitter:image:src'
+  <meta content='freeCodeCamp.org' name='twitter:title' />
-/>
+  <meta content={ 'Learn to code. Build projects. Earn certifications.'
-<meta content='freeCodeCamp.org' name='twitter:title' />
+    + 'Since 2015, 40,000 graduates have gotten jobs at tech '
-<meta
+    + 'companies including Google, Apple, Amazon, and Microsoft.' } name='twitter:description' />
-  content={
-    'Learn to code. Build projects. Earn certifications.' +
-    'Since 2015, 40,000 graduates have gotten jobs at tech ' +
-    'companies including Google, Apple, Amazon, and Microsoft.'
-  }
-  name='twitter:description'
-/>
 
 
   <!-- Theme -->
@@ -85,8 +70,11 @@
       },
 
       pagination: {
-        crossChapter: true,
+        crossChapter: false
-        crossChapterText: true,
+      },
+
+      remoteMarkdown: {
+        tag: 'remote-markdown-url',
       },
 
     }
@@ -104,5 +92,6 @@
   <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/docsify-plugin-flexible-alerts@1"></script>
   <script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
+  <script src="//unpkg.com/docsify-remote-markdown/dist/docsify-remote-markdown.min.js"></script>
 
-</html>
+</html>