Marty Hernandez Avedon
6ccd0b7b6c
* Syncing sidebar labels with page titles Deploying Rancher Server: Update sidebar label to match title * Installing/Upgrading Rancher: Update title to match sidebar This is a reference/hub page for install guides with no step-by-step instructions, so we're breaking the -ing rule to match other reference pages as well as the current sidebar label * Cluster Access: Update title to match sidebar * Kubernetes Persistent Storage: Volumes and Storage Classes - Update title to match sidebar * Don't have a Kubernetes cluster? Try one of these tutorials: Update title to match sidebar and make old title intro to page * Don't have infrastructure for your Kubernetes cluster? Try one of these tutorials: Update title to match sidebar and make old title intro to page * versioning Deploying Rancher Server update to other sidebars * Setting Up Kubernetes Clusters in Rancher: Update sidebars to match title and other sidebar labels * capitalization * Creating a vSphere Cluster: Update sidebar to match title and other labels * Creating a Nutanix AOS Cluster: Update sidebar to match title and other labels * Kubernetes Clusters in Rancher Setup across the board for title and sidebar, to match convention in sidebar * Kubernetes Resources: Updated title to match sidebar and distinguish from identically-titled page in troubleshooting section * The Horizontal Pod Autoscaler: Updated title to match sidebar * Backups and Disaster Recovery: Update title to match sidebar * typo fix * revert to Installation and Upgrade of Rancher fix typo in title: Create Kubernetes Persistent files * fix typo in Persistent Storage files * Configuration: Update title to match sidebar item Monitoring V2 Configuration Guides * Setup Guide: Make both sidebar + title Istio Setup guides to match other sidebar labels * Best Practices: Update both to Best Practice Guides * Architecture: Update to match sidebar Rancher Architecture. Note that there are multiple pages with identical titles, one is on Fleet and another on some other subject * Architecture: Retitle logging-architecture.md files Logging Architecture * Architecture: Retitle fleet/architecture.md files Fleet Architecture * GKE Cluster Configuration: Update sidebar to match title and other labels in same section * Security: Update both to Rancher Security Guides * RKE Hardening Guide: Update to match sidebar * typo * RKE2 Hardening Guide: Update to match sidebar * K3s Hardening Guide: Update to match sidebar * various FAQ pages: Add FAQ to title to disambiguate content * Cloud Native Storage with Longhorn: Versioning so older pages match current title * rm international pages for now * typo in metadata killed build * updated sidebar: plural Istio Setup Guides * updating Monitoring Config Guides title/label and distinguishing from similar section under References * monitoring V2 config examples: rm 'V2' * Kubernetes Cluster Setup > Setting up a Kubernetes Cluster for Rancher Server
Contribute to Rancher Docs
Welcome to the Rancher docs repository. See the Rancher software 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:
- Open an issue.
- Edit the docs in the way you see fit and open a pull request.
Edit the Docs
To get started, 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.
For most updates, you'll need to edit a file in the /docs directory, which represents the "Latest" version of our published documentation. The "Latest" version is a mirror of the most recently released version of Rancher. As of December 2023, the most recently released version of Rancher is 2.8.
Whenever an update is made to /docs, you should apply the same change to the corresponding file in /versioned_docs/version-2.8. If a change only affects older versions, you don't need to mirror it to the /docs directory.
If a file is moved or renamed, you'll also need to edit the sidebars.js files for each affected version, as well as the list of redirects in docusaurus.config.js. See Moving or Renaming Docs.
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. 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. We refer to the Microsoft style guide and use standard American English. Many pages are also available in Simplified Chinese.
Every docs page contain metadata in the first few lines:
---
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.
Run the Docs Website
The Rancher Docs website is built with Docusaurus 2, a modern static website generator.
You can run the site on your local machine, to preview how pages on your working branch will look live.
First, install Docusaurus 2:
- If you haven't already, install Node and Yarn.
- Go into your local rancher-docs folder.
- The Rancher Docs repository already contains a yarn.lock file, which contains the dependencies you need to build the website. Run
yarnto install Docusaurus and associated dependencies.
Start Site
yarn start
This command starts a local development server for Docusaurus 2, and opens up a browser window. Most changes are reflected live without having to restart the server.
Note: The yarn start command won't include some important static site features. For example, switching between languages from the site's dropdown menu is not available. If you need these features, use yarn build.
Build Site
yarn build
This command generates static content into the build directory and can be served using any static contents hosting service.
Launch With Docker
You can also use Docker to launch the website.
The below command can be used to install the dependencies and run the site inside a container:
docker run --rm -it -v $PWD:$PWD -w $PWD -p 3000:3000 node:18 /bin/sh -c "yarn install && yarn start -h 0.0.0.0"
Subsequent executions will check for updated dependencies, if there are none, it will skip the updates and quickly start the server.
License
Copyright (c) 2014-2024 Rancher Labs, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.