Skip to main content

​
VitePress

Know what? You’re looking at VitePress right now! It is asuprt lightwieght and powerful static site builder, and wonderful for building out documentation like this.

​
Helpful resources

​
How we use VitePress

We use VuePress to publish documentation for quick reference as a team, and for specific application developer documentation.

​
Structuring documentation

​
Folder structure

To keep thing organised we use a folder structure to categories documentation. This is also helpful when building out the sidebar. 
index.md
| folder_1
| - doc_1.md
| - doc_2.md
| folder_2
| - doc_3.md
Based off the folder structure we can build a sidebar that categorises documentation into helpful areas 
themeConfig: {
    sidebar: [
      {
        text: "Folder 1",
        items: [
          { text: "Doc 1", link: "/folder_1/doc_1" },
          { text: "Doc 2", link: "/folder_1/doc_2" },
        ],
      },
      {
        text: "Folder 2",
        items: [
          { text: "Doc 1", link: "/folder_2/doc_3" },
        ],
      },
    ],
  },

​
Adding images

To add static assets like images/files we add them in the folder of the referencing document within an images folder using the following convention: {document_name}_{image_name}.png You can then reference them directly in the document: ![Image name](./images/{document_name}_{image_name}.png)

​
Making changes

There is no develop branch of the VuePress instance, all changes are merged to the main branch. Changes to VuePress documentation are categorised into two types
  • Standard
  • Hotfix

​
Standard changes

95% of the time your change will be a standard change. These can include:
  • Adding / removing new documentation page
  • Adding any structural changes to the documentation
  • Changing the configuration files of the documentation
  • Making an addition / significant ammendment to existing documentation
All standard changes need to be branched off and a pull request made to the main branch. Only the documentation owner needs to be added as a reviewer.

​
Hotfix changes

When you are making an insignificant change, you can do a hotfix change. These can include:
  • 1-2 line content changes / corrections
  • Spelling / format corrections
Hotfix changes can be commited straight to the main branch