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

Merge pull request #362 from martyav/readme-update

Browse Source 
Info on style, formatting, docs organization + clarifying some details about local dev
This commit is contained in:
Billy Tat
2023-01-10 10:53:55 -08:00
committed by GitHub
parent e3f43e64df 592103d309
commit 219edb289c
1 changed files with 37 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+37 -14
View File
@@ -1,31 +1,46 @@
# Website
# 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](https://github.com/rancher/rancher-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 generally 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.
## Docs Website
The Rancher Docs website is built with [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
## Installation
You can run the site on your local machine, to preview how pages on your working branch will look live.
The Rancher Docs repository already contains a yarn.lock file, which contains the dependencies you need to build the website.
First, install Docusaurus 2:
1. If you haven't already, install [Node](https://nodejs.org/en/download/) and [Yarn](https://yarnpkg.com/getting-started/install).
1. Fork and clone the rancher-docs repository.
1. Go into your local rancher-docs folder.
1. Run `yarn` to install Docusaurus and associated dependencies.
1. The Rancher Docs repository already contains a yarn.lock file, which contains the dependencies you need to build the website. Run `yarn` to install Docusaurus and associated dependencies.
## Local Development
### Start Site
```
yarn start
```
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
This command starts a local development server for Docusuarus 2, and opens up a browser window. Most changes are reflected live without having to restart the server.
You can also use Docker to launch the website without needing to install and configure Yarn:
**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`.
```
docker run --rm -it -v $PWD:$PWD -w $PWD -p 3000:3000 node yarn start -h 0.0.0.0
```
## Build
### Build Site
```
yarn build
@@ -33,6 +48,14 @@ yarn build
This command generates static content into the `build` directory and can be served using any static contents hosting service.
### Launch With Docker
Use [Docker](https://www.docker.com/) to launch the website without needing to install and configure Yarn:
```
docker run --rm -it -v $PWD:$PWD -w $PWD -p 3000:3000 node yarn start -h 0.0.0.0
```
License
=======
Copyright (c) 2014-2022 [Rancher Labs, Inc.](https://rancher.com)
@@ -47,4 +70,4 @@ 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.
limitations under the License.