freeCodeCamp/docs/how-to-work-on-the-docs-the...

60 lines
2.9 KiB
Markdown
Raw Normal View History

# How to Work on Documentation
## Work on the Content of the Docs
To work on the contributing guidelines, you can edit or add files in the `docs` directory [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/main/docs). When your changes are merged, they will be made available automatically at the documentation site.
When adding a new file to the `docs` directory, you should evaluate if the file should also be added to the sidebar navigation. We typically create a link in the [`_sidebar.md`](_sidebar.md) file for new and independent guides. Alternatively, You may follow the instructions below on creating an internal link for supporting guides.
### How to Create an Internal Link
If you want to create a link targeting a different section of the contributing guidelines, follow this format:
```md
[Link text](target-file-name.md#target-section-heading-id)
// If the target section is within the same page, you can omit the file name
[Link text](#target-section-heading-id)
```
Make sure you include the file extension (`.md`). Don't specify the full URL or append `/` before the file name.
This is necessary to make these links work for the translated version of the document. Otherwise, they will redirect to the English version of the page regardless of the language.
#### Translating docs with internal links
When you work on translating docs on Crowdin, make sure to replace the `#target-section-heading-id` with the id on the translated document. [Learn more about translating docs here](how-to-translate-files.md#translate-documentation).
## Work on the Docs Theme
> [!NOTE]
> A quick reminder that you do not need to set up anything for working on the content for the documentation site.
>
> To work on the contributing guidelines, see [work on the docs content](#work-on-the-docs-content) section.
### Structure of the Docs Website
The 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. In case you are interested, here is how it works:
- The homepage's source for this site is available in [`docs/index.html`](index.html).
- We serve this file as a SPA using `docsify` and GitHub Pages.
- The `docsify` script generates the content of `markdown` files in the `docs` directory on demand.
- The homepage is generated from the [`_coverpage.md`](_coverpage.md).
- The sidebar navigation is generated from [`_sidebar.md`](_sidebar.md).
### Serving the Documentation Site Locally
Install freeCodeCamp locally ([see the local setup guide](how-to-setup-freecodecamp-locally)), we bundled the CLI with the development tools so you can run the command below as needed from the root of the repo:
```console
feat: migrate to pnpm for better workspace DX (#49293) * feat: npm -> pnpm This resolves the issues with the gatsby client (gatsby-plugin-pnpm deals with the fact that gatsby is relying on its own dependencies being de-duped) and challenge-editor (which doesn't seem to want to automatically install codemirror and needed its own eslint config) * fix: correct mocha path for curriculum tests * fix: use select workspace with -F not -w * fix: reorganise packages and restrict hoisting pnpm works best if the workspaces keep their own dependencies, since dependencies are not flattened and then what node resolves from a require is predictable. @types seem to be a special case and more care is required to prevent them getting smushed together in the root (hence the .npmrc) * fix: add types for tools + root * fix: decouple challenge-auditor from client * fix: add ui-components types * fix(client): use the latest types for react 16 * fix: prettify * fix: prettierignore pnpm-lock * fix: relax hoisting Turns out pnpm works just fine with types. I don't know what was going wrong before, but there are no-longer any type conflicts. * fix: add @redux-saga/core to fix eslint issue It seems to only be redux-saga that import/named can't cope with, so it is probably okay to work around this one. * chore: add chai to tools/scripts/build * fix: add store to root for cypress * fix: allow cypress to download binaries If we want to keep preventing cypress from downloading binaries, we can figure out a workaround, but I'm allowing it to ease the transition to pnpm. My guess about why this is happening is that npm triggers Cypress's postinstall script, but pnpm does not (because pnpm install only installs if necessary, perferring to link) * chore: re-enable pre/post scripts * fix: update build scripts for client Co-authored-by: Shaun Hamilton <shauhami020@gmail.com> * chore: update engines to use pnpm * fix: enable choice of (super)block for tests Only 'nix machines for now. * chore: pin pnpm to version 7 * chore: remove last npms Except web + curriculum-server. I'll update them when I start work on them again. * fix: lockfile check to catch any package-locks * fix(action): install pnpm for upcoming tests * chore: add nodemon to new api Co-authored-by: Shaun Hamilton <shauhami020@gmail.com>
2023-03-02 18:17:44 +00:00
pnpm run docs:serve
```
> The documentation site should be available at <http://localhost:3400>
## Proposing a Pull Request (PR)
After you've committed your changes, check here for [how to open a Pull Request](how-to-open-a-pull-request.md).