Adding pages and sections in the handbook is as simple as adding new markdown files, and folders under the content folder.

First Considerations

First and foremost, consider the content you want to add, and whether it should be public or not public. Public data goes under the /content/it folder, non-public data goes in the private section under /content/private.

Second, decide where in the menu structure you would like to put a new page or section. We’re still developing the layout of the whole handbook, so there isn’t a lot of guidance yet, but we’re currently arranging content based on subject, such as “engineering”, and “procurement”. Also consider whether your content should be an whole new section (like “communications”) or simply a new page in an existing section.

Lastly, consider what you’d like the page title to be. Page titles correspond to file names by default. For example, a markdown file called “My Page.md” will yield a handbook page titled “My Page”. The exception to this are the _index.md pages inside a section, whose titles will default to the seciton (folder) name. _index.md files should always have a “title:” key in their front matter, described below.

Creating a Section

Hugo content sections correspond to folders. Creating a new section is as simple as creating a new folder, and inside that folder, adding an _index.md file.

The _index.md file corresponds to the content you see when clicking on a section in the left-sidebar menu. For example, if the page https://handbook.roivant.io/communications/, this corresponds to /content/communications/_index.md. The _index.md

Folders can be created directly in Typora, VScode, Atom or simply through Explorer or Finder.

Adding Pages to a Section

Whether you are creating a new section or adding a page to an existing one, the process is the same - simply locate the folder (section) in which you’d like to add a page, and add a new file there, such as “My New Page.md” (must have the .md extension). Feel free to use capitals, spaces and so on, since as described above, page titles correspond to the file names by default.

Adding Content to a Page File

Once you’ve determined what and where your new content will be, you’ll need to actually put some content into the page file.

Front Matter

You may notice that at the top of every page md file, there is a small block os text that looks like:

---
title: Adding Pages and Sections
slug: adding-pages-and-section
weight: 20
---

This is a small chunk of data about the page, called the “front matter”. In general, we use a simple front matter with just title, “slug” and “weight”, which you can copy from most any other page, paste into your new page at the top, and modify. Hugo supports a variety of options, documented in their page above, but here the most immediately useful:

Key	What it does
title	The page title as displayed in the handbook menus and at the top of the page. If absent, the page title will be the filename, minus the .md
slug	the page name in the URL. For example, this page’s slug yields a URL such as: https://handbook.roivant.io/handbook-usage/adding-pages-and-sections
weight	“weight” determines the ordering of pages in the lefthand menu - the higher the weight, the lower the page listing in the menu. The lower the weight, the higher in the menu it will appear.
publishDate	e.g. “2021-10-01 (YYYY-MM-DD)”. If set in the future, Hugo will not display this page until that date
draft	“true” or “false”. If false, Hugo will not display the page. This allows you to create multiple pages, sections, etc. in “draft” state, commit them to Git, but they won’t show up on the site until you change draft to false, or delete the draft line

Adding the Page Content

At this point, you have considered whether to make a section or page, what to call it and where to put it. All that is left is to add some actual content. From this point on, it’s merely a matter of using markdown. You can author directly in markdown in e.g. VSCode, or in a more user-friendly way in Typora.

You can find basic syntax for markdown here.