#795 Update README w navigation and moving/renaming file info (#820)

* Added page about moving/renaming docs, new headings for readme

* added navigation section

* revised README

* revised moving-or-renaming-docs

* Apply suggestions from code review

Co-authored-by: Lucas Saintarbor <[email protected]>

* Update moving-or-renaming-docs.md - revamping schema example

* json > js

* typos, extra explanation

* json > js

* various changes

---------

Co-authored-by: Lucas Saintarbor <[email protected]>

Author: martyav

README.md

@@ -1,16 +1,31 @@
-# Edit The Docs
+# Contribute to Rancher Docs
 
-To get started, fork and clone the rancher-docs repository.
+Welcome to the [Rancher docs](https://ranchermanager.docs.rancher.com/) repository. See the [Rancher software](https://github.com/rancher/rancher) repository if you have questions or requests for the Rancher platform.
+
+## Make a Suggestion
+
+You can suggest changes to the Rancher docs in two ways: 
+
+1. [Open an issue](https://github.com/rancher/rancher-docs/issues/new/choose).
+1. Edit the docs in the way you see fit and open a pull request.
+
+## Edit the Docs
+
+To get started, [fork](https://github.com/rancher/rancher-docs/fork) and clone the rancher-docs repository.
 
 Our repository doesn't allow you to make changes directly to the `main` branch. Create a working branch and make pull requests from your fork to [rancher/rancher-docs](https://github.com/rancher/rancher-docs).
 
 For most updates, you'll need to edit a file in `/docs`, and the corresponding file in `/versioned_docs/version-2.7`. If a change affects older versions, you can find files documenting Rancher v2.0 and later in the `/versioned_docs` directory. 
 
-If a file is moved or renamed, you'll also need to edit the `sidebars.js` files for each version, and the list of redirects in `docusaurus.config.js`. 
+If a file is moved or renamed, you'll also need to edit the `sidebars.js` files for each version, and the list of redirects in `docusaurus.config.js`. See [Moving or Renaming Docs](./moving-or-renaming-docs.md).
+
+### Navigate the Repo
+
+The file paths in the repo correspond to the URLs for pages on the docs website. The docs for the latest version of Rancher are located in `/docs`. Most index pages are found within the `/pages-for-subheaders` directory in `/docs`. All images are in `/static/img` in the top level of the repo. Older docs are found within `/versioned_docs` and generally follow the same structure as the files in `/docs`.
 
-## Style & Formatting
+### Style & Formatting
 
-The docs are written in [Markdown](https://www.markdownguide.org/getting-started/). We refer to the Microsoft [style guide](https://learn.microsoft.com/en-us/style-guide/welcome/) and generally use standard American English. Many pages are also available in Simplified Chinese.
+The docs are written in [Markdown](https://www.markdownguide.org/getting-started/). We refer to the Microsoft [style guide](https://learn.microsoft.com/en-us/style-guide/welcome/) and use standard American English. Many pages are also available in Simplified Chinese.
 
 Every docs page contain metadata in the first few lines:
 
@@ -22,7 +37,7 @@ title: Some Title
 
 The `title` is rendered as the page's headline. The site renderer wraps the `title` value in `H1` tags, which are equivalent to `#` in Markdown syntax. This means that all subsequent headers on the page should be second level (`##`) or more.
 
-## Docs Website
+## Run the Docs Website
 
 The Rancher Docs website is built with [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
 

moving-or-renaming-docs.md

@@ -0,0 +1,67 @@
+# Adding, Moving, or Renaming Docs
+
+Docusaurus generates sidebars based on a JSON file named `sidebars.js`. When you add a new doc, you need to add an entry to `sidebars.js`. Otherwise, the page won't appear in the list of sidebar topics. When you move or re-title a doc, you need to update `sidebars.js` to reflect the change to the doc's location or title. If you alter a docs file's path, by moving the file or editing the file's name, you'll also need to add a redirect to the new path in `docusaurus.config.js`.
+
+> **Note:** Avoid adding filenames that contain periods before the file extension (example: `rke2-self-assessment-guide-with-cis-v1.23-k8s-v1.25.md`). If necessary, use dashes instead of periods (`rke2-self-assessment-guide-with-cis-v1-23-k8s-v1-25.md`).
+
+## Sidebars
+
+The `sidebars.js` file for the latest version of Rancher is located in the top level of the repo. Versioned docs each have their own versioned sidebar, found within `/versioned_sidebars` in the top level of the repo.
+
+The schema for `sidebars.js` looks like this: 
+
+```JS
+sidebar: [
+    "toplevel",
+    {
+        type: "category",
+        label: "Second Level",
+        items: [
+            "second-level/overview",
+            {
+                type: "category",
+                label: "Topic One",
+                link: {
+                    type: "doc",
+                    id: "pages-for-subheaders/index-page-for-topic-one"
+                }
+                items: [
+                    "second-level/topic-one/page-a",
+                    "second-level/topic-one/page-b",
+                ]
+            }
+        ]
+    }
+]
+```
+
+Paths for docs files are listed within an `items` array. Their position within the file is similar to how they'll be organized within the published sidebar. 
+
+If the doc is as an index page for a topic with numerous subtopic pages, its entry in `sidebars.js` should have extra metadata, such as `category`, `link`, and `label`.
+
+### Moving Index Pages
+
+Some entries in the published sidebar are clickable dropdown menus. When a reader clicks them, they reveal a list of subtopics. These dropdown menu entries are indicated by `type: category` in the sidebar file. When you select the entry on the published docs site, the menu opens and you will navigate to the page indicated in `link.id`. 
+
+Docusaurus uses the `label` field to generate the text that appears on the dropdown menu in the sidebar. When you rename these index pages, you also need to update their `label` in the sidebar file.
+
+### Redirecting Pages
+
+When you move a page, update redirects in the `@docusaurus/plugin-client-redirects` field within the `docusaurus.config.js` file. This file is located in the top level of the repo.
+
+The schema for docs redirects looks like this:
+
+```JS
+          {
+            to: '/faq/general-faq',
+            from: '/faq'
+          }
+          {
+            to: '/v2.6/faq/general-faq',
+            from: '/v2.6/faq'
+          },
+```
+
+Docusaurus redirects don't accept wildcards, so each path must be exact. This means that you must add individual redirects for each version of a doc. 
+
+Docusaurus also can't redirect pages whose filenames contain a period before the extension. You'll need to manually update any docset links to those pages.