public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-09 10:45:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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 <lucas.saintarbor@suse.com>

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

* json > js

* typos, extra explanation

* json > js

* various changes

---------

Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com>
This commit is contained in:
Marty Hernandez Avedon
2023-09-13 16:39:08 -04:00
committed by GitHub
co-authored by Lucas Saintarbor
parent 6c332ea0e6
commit a7c4d606ee
2 changed files with 88 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+21 -6
View File
@@ -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).
## Style & Formatting
### Navigate the Repo
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 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
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
+67
View File
@@ -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.