To create a new page in the Handbook you follow these steps:
- Create an issue in the handbook repo
- 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
- Click on the name of your branch after “Request to Merge” to open that branch in the repository file view.
- Open the
content/docsfolder. This is where webpages are stored.
- Choose the directory where you want your webpage to be. For example, if you put a page in the
marketingfolder it will show up at the “root” level, if you create the new directory inside of another directory it will appear at that path.
- Click to add a
New directoryfrom the plus sign drop down.
- 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
salesdirectory and inside the
salesdirectory create a new directory called
- Click to add a
New filefrom the plus sign drop down
- Name the file
- 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.
- Inside the quote add the title of your page.
- 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.)
- Return to the directory you created. You will see that you now have two files:
.gitkeep. Delete the
.gitkeepfile. 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
.gitkeepfile on your branch. Click the “delete” button to delete the file.
- ProTip: Add a link to the bottom of your page so people can continue reading related content. Popular choices would be
/engineeringor any pages related to your page.
- If you need help you can ask in the #handbook Slack channel.