Skip to main content

Add New Site

To add a new site to the docusaurus instance please follow this guide. There are some important steps that aren't directly obvious but important to perform correctly otherwise the Docusaurus build could fail or the site won't be working as expected.

1. Add the docs site​

Add an array to the plugin array which contains 2 fields.

  1. @docusaurus/plugin-content-docs
  2. An object with settings for this plugin.
docusaurus.config.js
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'new-project',
        path: 'docs/new-project',
        routeBasePath: 'new-project',
        sidebarPath: require.resolve('./docs/new-project/sidebars.js'),
        editUrl: (options) => 'https://github.com/almanak-co/new-project/tree/dev/docs/' + options.docPath
      },
    ],
    ...
  ]

Using this plugin we have seperate versioning for every docs site and can easily keep everything seperated. Make sure to have a unique name and replace all the new-project tags in this example with the Github repository name for exmaple; for the project almanak-co/simulation-modules this name is simulation-modules

2. Add the navbar items​

docusaurus.config.js
  themeConfig:
    ({
      // ...
      navbar: {
        // ...
        items: [
          // ...
          {
            type: 'docSidebar',
            sidebarId: 'new-project',
            position: 'left',
            label: 'New Project',
            docsPluginId: 'new-project',
          },
          // ...
          {
            type: 'docsVersionDropdown',
            docsPluginId: 'new-project',
            position: 'right',
          },
          // ...
        ]
      }
    })

Here you need to make sure that the sidebarId and docsPluginId are the same as the id you set previously in step 1. And make sure to give the label a good name.

The docsVersionDropdown is here to allow versioning of the docs site seperatly from all the other documentation on the site. Only the currently selected docs site and it's respective docsVersionDropdown will be shown.

3. Create an initial folder for the project.​

Duplicate the folder docs/example and give it the same name as you named the id in the first step. For example in this case when the id was new-project. You would duplicate the docs/example folder into docs/new-project.

Then edit the file sidebars.js and rename the top item in the sidebars object to the string of the id you set in step 1. In this case new-project would look like this:

docs/new-project/sidebars.js
const sidebars = {
  'new-project': [
    // ...
  ]
};

(Optional) Add an item to the front page.​

src/components/HomepageFeatures/index.tsx
const FeatureList: FeatureItem[] = [
  // ...
  {
    title: 'New Project',
    png: "/img/computer.png",
    description: (
      <>
        New Description
      </>
    ),
  },
];

Set the correct title and description (try to keep the description short). And optionally you can also upload a new image to the static/img/ folder and set path to the image correctly.

4. Push changes​

Make sure the site builds by performing

$ npm run build

If it builds succesfully you can push the changes to git and wait for the Github CI to finish building and deploying your site. When it's deployed it will be very empty, but we're about to change that.

5. Add docs to project repository​

Create a docs folder in your project repository and copy all the contents of the newly duplicated folder from the docs-internal project to your project. (copy from docs-internal/docs/* to docs-internal/new-project/docs/). The new-project here needs to be the same as the Github Repository name (for almanak-co/simulation-modules this name is simulation-modules).

This should initially include two files intro.md and sidebars.js.

You can start modifying files now. To find instructions on how to write docs please go here.

6. Automatically deploy docs from your project​

Now that you've writen some documentation we need to setup a CI so that every time that you change anything in your documentation it will automatically be deployed on the docusaurus site.

There are two parts to this.

  1. Deploying your next version.
  2. Versionised docs for old versions (COMING SOON)

1. Deploying your next version​

Please add the following file to your project. This sets up a Github CI workflow that every time a push is done on your dev branch that has changes on the docs/ folder it will automatically push those changes to the almanak-co/docs-internal Github project. Which will in turn automatically deploy it using it's own Github CI.

.github/workflows/publish_docs.yaml
name: Push to Dev

on:
  push:
    branches:
      - dev
    paths:
    - 'docs/**'

jobs:
  publish:
    name: Publish docs
    runs-on: ubuntu-latest

    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
      - name: Checkout 🛎
        uses: actions/checkout@v3
        with:
          repository: 'almanak-co/docs-internal'
          ssh-key: ${{ secrets.INTERNAL_DOCS_DEPLOY_KEY }}
        
      - name: Set REPONAME
        run: |
          echo "REPONAME=$(echo $GITHUB_REPOSITORY |  awk -F '/' '{print $2}')" >> "$GITHUB_ENV"

      - name: Get latest docs
        run: |
          git remote add -f -t $GITHUB_REF_NAME --no-tags ${{ env.REPONAME }} https://github.com/$GITHUB_REPOSITORY.git
          git rm -rf docs/${{ env.REPONAME }}/
          git read-tree --prefix=docs/${{ env.REPONAME }}/ -u ${{ env.REPONAME }}/$GITHUB_REF_NAME:docs
      
      - name: Checkout additional files
        uses: Bhacaz/checkout-files@v2
        with:
          files: config/sample.yaml
          branch: ${{ github.head_ref || github.ref_name }}

      - name: Move additional files
        run: |
          mv config/sample.yaml docs/${{ env.REPONAME }}/sample.yaml

      - name: Push updated docs to internal docs
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: ':memo: Update Docs'
          commit_user_name: Github Actions Bot

You shouldn't need to make any updates to this CI specification, it has been preconfigured to use all the available Github CI Variables.

You can also choose depending on your workflow to change the branch at the top to main or another name for the branch that you would like this workflow to trigger for.

The one item that we're missing here is setting the INTERNAL_DOCS_DEPLOY_KEY in the Github CI Secrets. This has to be done by following this guide. For this you do need admin access to both your repository where the docs will live and the docs-internal repository. If you would like to do this please tag @Koen on Slack and he can help you with getting the correct permissions or doing this step for you.

2. Versionised docs for old versions​

COMING SOON, tag @Koen in Slack if you need this.