|
| 1 | +--- |
| 2 | +sidebar_position: 5 |
| 3 | +sidebar_label: "About These Docs" |
| 4 | +slug: "about-these-docs" |
| 5 | +title: "About These Docs" |
| 6 | +--- |
| 7 | +import { Highlight } from "../src/components/Highlight"; |
| 8 | + |
| 9 | +# ✏️️ Contributing |
| 10 | + |
| 11 | +These docs are built with [Docusaurus](https://github.com/facebook/docusaurus) and deployed to GitHub Pages. Check |
| 12 | +out [this page](https://docusaurus.io/docs/create-doc) to read more about how to create pages with Docusaurus. |
| 13 | +It offers many features out of the box which made it easy to adopt, such as versioning, i18n, and search. |
| 14 | + |
| 15 | +**To make changes to files**, click the "Edit this Page" link at the bottom of any page. This will prompt you to create a pull request on GitHub with your proposed changes. Alternatively, you can edit the file directly from GitHub and create the pull request from there. |
| 16 | + |
| 17 | +## Running Docs Locally |
| 18 | + |
| 19 | +If you'd like to run the docs locally, you should clone the repo to your laptop. |
| 20 | + |
| 21 | +### GitHub Repo |
| 22 | + |
| 23 | +The repository for these docs lives here: [securesign/ssc-hub](https://github.com/securesign/ssc-hub) |
| 24 | + |
| 25 | +### What you'll need |
| 26 | + |
| 27 | +- [Node.js](https://nodejs.org/en/download/) version 18.0 or above: |
| 28 | + - When installing Node.js, you are recommended to check all checkboxes related to dependencies. |
| 29 | + |
| 30 | +### Start the site |
| 31 | + |
| 32 | +Run the development server: |
| 33 | + |
| 34 | +```bash |
| 35 | +npm run start |
| 36 | +``` |
| 37 | + |
| 38 | +The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. |
| 39 | + |
| 40 | +The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. |
| 41 | + |
| 42 | +Open `docs/intro.md` and edit some lines: the site **reloads automatically** and displays your changes. |
| 43 | + |
| 44 | +## Deploying Changes |
| 45 | + |
| 46 | +Changes are published automatically on push to the `main` branch of the [securesign/ssc-hub](https://github.com/securesign/ssc-hub) repository, which is private to members of the `securesign` org. The workflow responsible for deployment is located here: [.github/workflows/deploy.yml](https://github.com/securesign/ssc-hub/blob/main/.github/workflows/deploy.yml) |
| 47 | + |
| 48 | +The docs are deployed using [GitHub Pages](https://pages.github.com/) and are private thanks to Red Hat having an enterprise plan. Check the [repo Pages settings](https://github.com/securesign/ssc-hub/settings/pages) for additional info. |
| 49 | + |
| 50 | +## How to add new things |
| 51 | + |
| 52 | +### Add a new page to an existing category in the sidebar |
| 53 | + |
| 54 | +Simply drop a Markdown (or MDX) file in the category directory. For example, if you want to add a new page to "Resources", you would add the file to `docs/resources` directory. |
| 55 | + |
| 56 | +:::info |
| 57 | +Make sure your Markdown file contains a `h1` header, as otherwise it will just use the name of the file, which is usually ugly. |
| 58 | +::: |
| 59 | + |
| 60 | +### Add a new category in the sidebar |
| 61 | + |
| 62 | +1. Create a new folder within the `docs` directory with the name of the path you want (i.e. `http://localhost:3000/new-category/`) |
| 63 | +2. Add a `_category_.json` file (you can use the other categories as an example) and populate it as follows: |
| 64 | + |
| 65 | +```json |
| 66 | +{ |
| 67 | + "label": "Example", |
| 68 | + "position": 80, |
| 69 | + "link": { |
| 70 | + "type": "generated-index", |
| 71 | + "description": "Some example description." |
| 72 | + } |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +The `position` property determines where in the sidebar it appears in relation to the other categories. Try to use increments of 10 or 20, when possible. |
| 77 | + |
| 78 | +3. Add a Markdown file in the new directory (i.e. `docs/new-category/some-page.md`) |
| 79 | +4. If there were no errors, the page will now be available at `http://localhost:3000/new-category/some-page` |
| 80 | + |
| 81 | +### Add a new top-level navigation item |
| 82 | + |
| 83 | +At the very top there is a navigation bar with a few menu items, a search bar, and a few other things. We mainly use the `docs` page, but if you'd like to add a new item, you can add a markdown file with the item under `src/pages`. Here is an example of the one used to create the F2F page (`src/pages/f2f.md`): |
| 84 | + |
| 85 | +```markdown |
| 86 | +--- |
| 87 | +slug: /about |
| 88 | +title: About |
| 89 | +--- |
| 90 | + |
| 91 | +# About |
| 92 | + |
| 93 | +This is my example page. |
| 94 | +``` |
| 95 | + |
| 96 | +If you'd like to add a completely new custom style page (similar to how we do for the Blog), have a look at how we do it for the blog (`blog` folder in root of directory). |
| 97 | + |
| 98 | +### Add a new Mermaid diagram |
| 99 | + |
| 100 | +[Mermaid](https://mermaid.js.org/syntax/flowchart.html) is supported by Markdown and Docusaurus, meaning you can now create a diagram from anywhere in the repo with a simple code block: |
| 101 | + |
| 102 | +``` |
| 103 | +```mermaid |
| 104 | +flowchart LR |
| 105 | + A -- text --> B -- text2 --> C |
| 106 | +``` |
| 107 | + |
| 108 | +Which will render the following: |
| 109 | + |
| 110 | +```mermaid |
| 111 | +flowchart LR |
| 112 | + A -- text --> B -- text2 --> C |
| 113 | +``` |
| 114 | + |
| 115 | +Mermaid supports several types of diagrams, not just flowcharts. If you'd like to play around with Mermaid, there is a live editor [here](https://mermaid-js.github.io/). |
| 116 | + |
| 117 | +### Add an interactive React component |
| 118 | + |
| 119 | +Docusaurus lets you add interactivity via [MDX](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components. All you have to do is name your file using the `.mdx` extension instead of `.md` and include your component as usual. |
| 120 | + |
| 121 | +Here is an example: |
| 122 | + |
| 123 | +<Highlight color="#25c2a0">This is highlighted</Highlight> and <Highlight color="#1877F2">so is this</Highlight>, using a custom `<Highlight/>` component in the `src/components` directory. |
| 124 | + |
| 125 | +I can write **Markdown** alongside my _JSX_! |
0 commit comments