Contributing

Contributing new or updated documentation to Hermes is very easy.

Editing Existing Content

1. Use the bottom-of-page link or clone the repo and make adjustments to the existing file.
2. Create a Merge Request for the changes to enter the master branch.
3. Once merges, the pipeline will auto-generate and publish the new docs.

Adding a New Page

Using an Existing Sidebar

If your page can be categorized under an existing sidebar entry follow these steps. In the examples we'll add a new page under /aws/ about security groups.

1. Create a new .md file with the URL-friendly path name of your desired page within the appropriate /docs/ sidebar directory (e.g. /docs/aws/security-groups.md):

touch docs/aws/security-groups.md

2. Add content to the .md file:

---
title: Security Groups
---

# Security Groups

- TODO: This page should contain information about developer-specific AWS Security Groups.

3. Open /docs/.vuepress/config.js.
4. Add a new entry in the themeConfig.sidebar[{title: 'aws'}].children array that matches the URL path of the new page (excluding the .md extension):

module.exports = {
  // ...
  themeConfig: {
    // ...
    sidebar: [
      // ...
      {
        // ...
        children: [
          // ...
          '/aws/security-groups'
        ]
      }
    ]
  }
}

5. Run yarn dev to rebuild and check your new page displays in the appropriate sidebar and can be viewed.

With a New Sidebar

If your page requires a new sidebar entry, follow these initial steps. To illustrate, we'll be creating a new page about this Hermes project that should be available at the URL /projects/hermes and be displayed under a new Projects sidebar menu.

1. Create a new directory under /docs/ to match the desired URL path (e.g. projects):

mkdir docs/projects 

2. Create a new .md file with the URL-friendly path name of your desired page (e.g. hermes.md):

touch docs/projects/hermes.md

3. Add content to the .md file:

---
title: Project: Hermes
---

# Project: Hermes

This is a new page about the Hermes project.

4. Add a new object to the themeConfig.sidebar array. The title is the string sidebar name, and the children array should be the full path to the new page(s) you want to link to:

module.exports = {
  // ...
  themeConfig: {
    // ...
    sidebar: [
      // ...
      {
        title: 'Projects',
        collapsable: false,
        sidebarDepth: 2,
        children: [
          '/projects/hermes'
        ]
      }
    ]
  }
}

5. Run yarn dev to rebuild and test the changes.

Adding Sidebar Index Pages

1. If you need a new page to be the index page of a sidebar path just name it index.md.
2. Ensure the themeConfig.sidebar object has a path property, which will automatically point to the index.md found in that directory. Here's the sidebar configuration of this very /docs/contributing/index.md file, to illustrate:

module.exports = {
  // ...
  themeConfig: {
    // ...
    sidebar: [
      // ...
      {
        title: 'Contributing',
        path: '/contributing/',
        collapsable: false,
        sidebarDepth: 2
      }
    ]
  }
}

Additional Help

See the VuePress official documentation for information on Markdown syntax, page/theme modifications, and much more.