Practical Edits

Creating a new page

To create a new page in the Handbook you follow these steps:

1. Create an issue in the handbook repo
2. Create an MR from the issue by clicking on the “Create Merge Request” button. This will create a new branch for you and link it to your issue and label the MR as WIP:.
3. Click on the name of your branch after “Request to Merge” to open that branch in the repository file view.
4. Open the content/docs folder. This is where webpages are stored.
5. Choose the directory where you want your webpage to be. For example, if you put a page in the marketing folder it will show up at the “root” level, if you create the new directory inside of another directory it will appear at that path.
6. Click to add a New directory from the plus sign drop down.
7. Name the directory in all lowercase with dashes-between-words for what you want the path of your page to be. For example if you want to create a page at about.brmbl.io/handbook/sales/readmesw then click on the sales directory and inside the sales directory create a new directory called readmes.
8. Click to add a New file from the plus sign drop down
9. Name the file _index.md
10. Add this code to the top of the file

description:
---
layout: handbook-page-toc
title: ""
description:
---
## Subheading

Here is your first paragraph replace this text.

10. Inside the quote add the title of your page.
11. Save your page by clicking “Commit changes”. (Using markdown you can add more content to the page. All you need is a title, subheading and a paragraph to get started.)
12. Return to the directory you created. You will see that you now have two files: _index.md and .gitkeep. Delete the .gitkeep file. This is a placeholder file from when you created the directory since git cannot track empty directories. A quick way to delete the file on the correct branch is to click on “edit” in the changes tab of your MR. This will open the file editor. click “cancel” and dismiss the popup that says “all changes will be lost”. This will then place you in the file view for the .gitkeep file on your branch. Click the “delete” button to delete the file.
13. ProTip: Add a link to the bottom of your page so people can continue reading related content. Popular choices would be /product , /sales, /engineering or any pages related to your page.
14. If you need help you can ask in the #handbook Slack channel.