From d302fc94e0a5d7368dc2aee16c9b7d1d7559d49f Mon Sep 17 00:00:00 2001 From: Mrugesh Mohapatra Date: Tue, 14 Apr 2020 17:14:12 +0530 Subject: [PATCH] docs: update docs about docs --- CONTRIBUTING.md | 7 +++++-- docs/README.md | 42 +++++++++++++++++++++++++++++++----------- 2 files changed, 36 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e21552ea4..d9acaefe23 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,7 @@ +> ### All our documentation and contributing guidlines are available on a dedicated site here: . -> ### Our contributing guidelines are available here: +### Looking to edit the contributing guidelines? -Looking to edit the contributing guidelines? The source is [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/docs). +To work on the contributing guidelines, you can edit these files [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/docs). When your changes are merged, it will be made available automatically at the documentation site linked above. + +**You do not need to setup anything locally for working on the documentation.** \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 81b3584011..b963707cfe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,17 +1,37 @@ -> ### Our contributing guidelines are available here: +> ### All our documentation and contributing guidlines are available on a dedicated site here: . -Looking to edit the contributing guidelines? The source is [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/docs). +### Looking to edit the contributing guidelines? -They are created using [docsify](https://docsify.js.org). The guideline homepage's source is [index.html](index.html), which generates the page from the content in [index.md](index.md). +To work on the contributing guidelines, you can edit these files [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/master/docs). When your changes are merged, it will be made available automatically at the documentation site linked above. -To run the docs locally, install `docsify` +**You do not need to setup anything locally for working on the documentation.** -```bash -npm i -g docsify -``` +### How is the documentation site generated? -and then use +The documentation site is generated using [`docsify`](https://docsify.js.org), and served using GitHub pages. Typically you would not need to change any configuration, or build the site locally, but incase you are interested here is how it works: -```bash -docsify serve docs -``` +1. The guideline homepage's source is [`index.html`](index.html). GitHub Pages serve this file as a SPA using `docsify`. +2. The `docsify` script generates the content of `markdown` files in `/docs` directory on demand when you are browsing the documentation site. +3. The home page is genrated from the [`index.md`](index.md) and sidebar navigation is generated from [`components/sidebar.md`](components/sidebar.md). +4. To serve the docs locally: + + Clone freeCodeCamp: + + ```sh + git clone https://github.com/freeCodeCamp/freeCodeCamp.git + docsify serve docs + ``` + + Install `docsify`: + + ```sh + npm install -g docsify + ``` + + and serve the `/docs` directory + + ```sh + docsify serve docs + ``` + + Alternatively, if you have installed freeCodeCamp locally (see the local setup guide), we bundle the CLI with the development tools so you can run `npm run docs:serve` from the root of the repo.