From 2b049892eb2a7965a21bb44fc4a68e193d0a7600 Mon Sep 17 00:00:00 2001 From: martyav Date: Mon, 9 Jan 2023 16:05:54 -0500 Subject: [PATCH 1/8] info on style, formating, organization + clarifying some details about local dev --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index a5793116fcd..1e7f7422d5f 100644 --- a/README.md +++ b/README.md @@ -2,28 +2,57 @@ The Rancher Docs website is built with [Docusaurus 2](https://docusaurus.io/), a modern static website generator. -## Installation +## Edit The Docs -The Rancher Docs repository already contains a yarn.lock file, which contains the dependencies you need to build the website. +To get started, fork and clone the rancher-docs repository. -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. +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 & Formating + +The docs are written in [Markdown](https://www.markdownguide.org/cheat-sheet/). 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 Standard Chinese. We plan to add more language support. + +Every docs page contain metadata in the first few lines: + +``` +--- +title: Some Title +--- +``` + +The title metadata is rendered as the published page's headline. The renderer wraps the content of the `title` in H1 level HTML header tagss, which are equivalent to `#` in Markdown syntax. This means that all subsequent headers on the page should be second level (`##`) or more. + +### Organization + +Folders and directories in the repo correspond to submenus in the site sidebar. We try to keep our submenus to a maximum of three levels deep, or four if absolutely necessary. + +The sidebar on the live site is rendered based on the contents of the file `sidebar.json`, which is located in the top level of the repository. If you move or delete a page, `sidebar.json` must be updated. ## Local Development +You can locally run the docs website to preview how pages will look live. + +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 +``` + +Otherwise, perform the following steps: + +1. If you haven't already, install [Node](https://nodejs.org/en/download/) and [Yarn](https://yarnpkg.com/getting-started/install). +1. Go into your local rancher-docs folder. +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. + +Once everything is installed, run the following: + ``` 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: - -``` -docker run --rm -it -v $PWD:$PWD -w $PWD -p 3000:3000 node yarn start -h 0.0.0.0 -``` +Note: The `yarn start` command won't include some important static site features. For example, the site will lack versioning for different languages. If you need to check different langusge versions, use `yarn build`. ## Build From 9e604dc5a0e1a9e2db2c6dcc26768ec1463630e5 Mon Sep 17 00:00:00 2001 From: martyav Date: Mon, 9 Jan 2023 16:20:42 -0500 Subject: [PATCH 2/8] typo fixes, reorganizaing headers, revising local dev sections --- README.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 1e7f7422d5f..7c923bb65ec 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,10 @@ -# Website - -The Rancher Docs website is built with [Docusaurus 2](https://docusaurus.io/), a modern static website generator. - -## Edit The Docs +# 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 & Formating +## Style & Formatting The docs are written in [Markdown](https://www.markdownguide.org/cheat-sheet/). 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 Standard Chinese. We plan to add more language support. @@ -22,15 +18,25 @@ title: Some Title The title metadata is rendered as the published page's headline. The renderer wraps the content of the `title` in H1 level HTML header tagss, which are equivalent to `#` in Markdown syntax. This means that all subsequent headers on the page should be second level (`##`) or more. -### Organization +## Organization Folders and directories in the repo correspond to submenus in the site sidebar. We try to keep our submenus to a maximum of three levels deep, or four if absolutely necessary. -The sidebar on the live site is rendered based on the contents of the file `sidebar.json`, which is located in the top level of the repository. If you move or delete a page, `sidebar.json` must be updated. +The sidebar on the live site is rendered based on the contents of the file `sidebar.json`, which is located in the top level of the repository. If you add, move, or delete a page, `sidebar.json` must be updated. -## Local Development +## Docs Website -You can locally run the docs website to preview how pages will look live. +The Rancher Docs website is built with [Docusaurus 2](https://docusaurus.io/), 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: + +1. If you haven't already, install [Node](https://nodejs.org/en/download/) and [Yarn](https://yarnpkg.com/getting-started/install). +1. Go into your local rancher-docs folder. +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. + +### Launch With Docker Use [Docker](https://www.docker.com/) to launch the website without needing to install and configure Yarn: @@ -38,13 +44,7 @@ Use [Docker](https://www.docker.com/) to launch the website without needing to i docker run --rm -it -v $PWD:$PWD -w $PWD -p 3000:3000 node yarn start -h 0.0.0.0 ``` -Otherwise, perform the following steps: - -1. If you haven't already, install [Node](https://nodejs.org/en/download/) and [Yarn](https://yarnpkg.com/getting-started/install). -1. Go into your local rancher-docs folder. -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. - -Once everything is installed, run the following: +### Start ``` yarn start @@ -52,9 +52,9 @@ yarn start 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. -Note: The `yarn start` command won't include some important static site features. For example, the site will lack versioning for different languages. If you need to check different langusge versions, use `yarn build`. +Note: The `yarn start` command won't include some important static site features. For example, the site will lack versioning for different languages. If you need these features, use `yarn build`. -## Build +### Build ``` yarn build From c3c6759ae8a308fdfc79e641b2de504ee835d74b Mon Sep 17 00:00:00 2001 From: Marty Hernandez Avedon Date: Mon, 9 Jan 2023 16:24:56 -0500 Subject: [PATCH 3/8] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7c923bb65ec..8dd018d05dc 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ title: Some Title --- ``` -The title metadata is rendered as the published page's headline. The renderer wraps the content of the `title` in H1 level HTML header tagss, which are equivalent to `#` in Markdown syntax. This means that all subsequent headers on the page should be second level (`##`) or more. +The title metadata is rendered as the published page's headline. The renderer wraps the content of the `title` in H1 level HTML header tags, which are equivalent to `#` in Markdown syntax. This means that all subsequent headers on the page should be second level (`##`) or more. ## Organization From 610bc32520cf325c39531b87c6556de05978fda0 Mon Sep 17 00:00:00 2001 From: Marty Hernandez Avedon Date: Mon, 9 Jan 2023 17:38:34 -0500 Subject: [PATCH 4/8] more revisions to README --- README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 8dd018d05dc..1e347ab8ebe 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,11 @@ title: Some Title --- ``` -The title metadata is rendered as the published page's headline. The renderer wraps the content of the `title` in H1 level HTML header tags, which are equivalent to `#` in Markdown syntax. This means that all subsequent headers on the page should be second level (`##`) or more. +The title metadata is rendered as the page's headline. The 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. ## Organization -Folders and directories in the repo correspond to submenus in the site sidebar. We try to keep our submenus to a maximum of three levels deep, or four if absolutely necessary. +Directories in the repo correspond to submenus in the site sidebar. We try to keep our submenus to a maximum of three levels deep, or four if absolutely necessary. The sidebar on the live site is rendered based on the contents of the file `sidebar.json`, which is located in the top level of the repository. If you add, move, or delete a page, `sidebar.json` must be updated. @@ -36,15 +36,7 @@ First, install Docusaurus 2: 1. Go into your local rancher-docs folder. 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. -### 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 -``` - -### Start +### Start Site ``` yarn start @@ -54,7 +46,7 @@ This command starts a local development server for Docusuarus 2, and opens up a Note: The `yarn start` command won't include some important static site features. For example, the site will lack versioning for different languages. If you need these features, use `yarn build`. -### Build +### Build Site ``` yarn build @@ -62,6 +54,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) @@ -76,4 +76,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. \ No newline at end of file +limitations under the License. From 8a654eefdc0e6a566963fc44729a2993d1f53176 Mon Sep 17 00:00:00 2001 From: Marty Hernandez Avedon Date: Mon, 9 Jan 2023 17:40:17 -0500 Subject: [PATCH 5/8] added backticks to one word --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1e347ab8ebe..748f3f80096 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ title: Some Title --- ``` -The title metadata is rendered as the page's headline. The 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. +The `title` is rendered as the page's headline. The 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. ## Organization From da6cc21d41997975d6e662e032347b37a4995b7f Mon Sep 17 00:00:00 2001 From: Marty Hernandez Avedon Date: Mon, 9 Jan 2023 17:42:39 -0500 Subject: [PATCH 6/8] sidebars, plural --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 748f3f80096..3fce1679c7f 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ The `title` is rendered as the page's headline. The renderer wraps the `title` v Directories in the repo correspond to submenus in the site sidebar. We try to keep our submenus to a maximum of three levels deep, or four if absolutely necessary. -The sidebar on the live site is rendered based on the contents of the file `sidebar.json`, which is located in the top level of the repository. If you add, move, or delete a page, `sidebar.json` must be updated. +The sidebar on the live site is rendered based on the contents of the file, `sidebars.json`, which is located in the top level of the repository. If you add, move, or delete a page, `sidebars.json` must be updated. ## Docs Website From 7342c507de19d074750437b76b0fe1e75e8b25c5 Mon Sep 17 00:00:00 2001 From: martyav Date: Tue, 10 Jan 2023 11:21:29 -0500 Subject: [PATCH 7/8] revised based on comments --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3fce1679c7f..8e0cabf1798 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Our repository doesn't allow you to make changes directly to the `main` branch. ## Style & Formatting -The docs are written in [Markdown](https://www.markdownguide.org/cheat-sheet/). 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 Standard Chinese. We plan to add more language support. +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: @@ -44,7 +44,7 @@ yarn start 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. -Note: The `yarn start` command won't include some important static site features. For example, the site will lack versioning for different languages. If you need these features, use `yarn build`. +**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 From 592103d309ad6003523abe9cf79225c82550b5b4 Mon Sep 17 00:00:00 2001 From: martyav Date: Tue, 10 Jan 2023 11:40:45 -0500 Subject: [PATCH 8/8] rm'd organization section, revised description of tag rendering --- README.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/README.md b/README.md index 8e0cabf1798..0ec1f5cb9a0 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,7 @@ title: Some Title --- ``` -The `title` is rendered as the page's headline. The 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. - -## Organization - -Directories in the repo correspond to submenus in the site sidebar. We try to keep our submenus to a maximum of three levels deep, or four if absolutely necessary. - -The sidebar on the live site is rendered based on the contents of the file, `sidebars.json`, which is located in the top level of the repository. If you add, move, or delete a page, `sidebars.json` must be updated. +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