How to Add and Edit Categories and Top Categories

Important

Adding and Editing Categories and Top Categories should be done via merging a forked repository. If you have not set one up, follow the instructions under "Fork the repository (One-time setup)" in Editing with Forks

Netlify CMS does not currently have functionality to add and edit categories.

---

Categories

It is useful to group rules into categories, for better perusal!

Add a rule to an existing category

Follow these steps:

1. Go to the category index public page (E.g. https://ssw.com.au/rules/rules-to-better-communication)
2. Click on 'edit in GitHub'
3. Click on the little pencil to edit the Markdown file
4. Add a new rule URI to the "index" list, in the desired position

Reorder an existing category

Follow the same steps 1-3 above, then update the list order by moving items around as needed.

---
type: category
title: Rules to Better Communication
guid: 471816bf-f0df-4835-bf4d-66a90f6f1adc
uri: rules-to-better-communication
experts: https://www.ssw.com.au/people/?skill=Scrum
consulting: https://www.ssw.com.au/consulting/scrum
index:
- some-rule
- another-rule
- some-other-rule
- a-fourth-rule
---
This is a summary for the category

Add a new category

If you think SSW.Rules need a whole new category for one or more rule, follow these steps to create it:

1. Go to your forked repository.
2. Decide on which Top Category your Category should belong to.
3. Open the categories/{top-category name} (e.g. categories/Communication) folder.
4. Click Add file | Create new file
5. Name your file {category name}.md (e.g. 'rules-to-better-communication.md').
6. In the your {category name}.md file, you need to add the following fields in the frontmatter
   • type: value must be set to 'category'
   • title: the title of the category, this will be display on the home page and the category page
   • index: A markdown list of URIs of the rules composing the category
   • uri: same as the name of the file without the .md extension
     • Use dashes in your URLs
     • Make short and readable URLs
   • guid: a unique guid used to identify the category in the Cosmos DB
     • You can use guidgen.com/ to get a guid
   • experts: An optional redirect to the SSW People page with a certain tag, e.g. https://www.ssw.com.au/people/?skill={{skill}}
   • consulting: An optional redirect to a consulting page, e.g. https://www.ssw.com.au/consulting/{{consulting-page}}
7. You can also add a summary for the category after the frontmatter.
8. Important: In the index.md file of the top category, add your category URI to the list of categories under index:

Frontmatter and summary example:

---
type: category
title: Rules to Better Communication
guid: 471816bf-f0df-4835-bf4d-66a90f6f1adc
uri: rules-to-better-communication
experts: https://www.ssw.com.au/people/?skill=Scrum
consulting: https://www.ssw.com.au/consulting/scrum
index:
- the-best-chat-tools-for-your-employees
- options-for-remote-meetings
- always-call-first-before-emailing
---
This is a summary for the category

Figure: Frontmatter example for a category

Tip: Don't add a new line after the front matter as this has caused issues in the past.

Edit a category

If you need to edit a category, follow these steps:

1. Go to your forked repository.
2. Find the category you want to edit under categories | {your category's top-category} | {your category}.md
3. Click on the pencil button.
4. Make the changes you want.
5. Merge your changes, see Merging Your Fork

For the SSW.Rules markdown syntax, read the sample page

WARNING: Do not leave categories empty.

---

Top Categories

A top category is a group of categories that are related!

Add a top-category

If you think rules could have a new top-category, follow these steps:

1. Go to your forked repository
2. Open the categories folder
3. Click Add file | Create new file
4. Name your file {top-category name}/index.md (e.g, 'software-development/index.md')
5. Edit the index.md file, and add the following fields in the frontmatter
   • type: value must be set to top-category
   • title: the title of the top-category, this will be display on the home page (e.g Software Development)
   • uri: the URI for the new category (e.g. software-development)
   • index: A markdown list of categories URI composing the top-category

Example top category:

---
type: top-category
title: Software Development
uri: software-development
index:
- rules-to-better-net-projects
- rules-to-better-architecture-and-code-review
- rules-to-better-azure
- rules-to-better-devops
- rules-to-better-mvc
- rules-to-better-bots
- rules-to-better-clean-architecture
- rules-to-better-bug-management-and-feedback
- rules-to-better-user-acceptance-tests-uat-for-bug-management
- rules-to-better-crm-for-developers
- rules-to-better-power-platform
- rules-to-better-sharepoint-for-developers
- rules-to-better-code-commenting
---

Figure: Frontmatter example for a top-category

Edit a top-category

To edit a top-category, follow these steps:

1. Go to your forked repository
2. Open the folder categories | {top-category name}
3. Open the index.md file
4. Click on the pencil to edit
5. Make the changes you want
6. Merge your changes, see Merging Your Fork