Customizing Content

Handoff comes with a preset package of content. You can edit the content on all of the existing pages. You can also add custom content to any section of the site.

The content is divided into two levels: Top level content and section content. These levels map to the menus, with top level content being displayed across the top of the site, and section content being displayed in the left sidebar menu.

When you start a new Handoff project, the installer will create a /pages directory, with a couple of boilerplate markdown pages. This directory will allow you to add new content, edit existing content, modify the menus, update metadata, and hide content. You can make all of these changes by adding and modifying markdown files in this directory.

Markdown Structure

Every page on Handoff has a corresponding markdown file. To change these pages, or add new pages, you will add a markdown file to your local /pages directory. This file should be named according to the url path on the site, with a md extension. The files start with a frontmatter yaml metadata block and then can accommodate any markdown.

Here is a sample top level file -

sample.md
1---
2title: A page title
3description: The hero description that appears at the top of the page.
4image: image # A class name of an svg to display in the hero
5weight: -5 # Weight will control the position in the top menu. Lower weight, higher up in the menu.  Higher weight, lower in the menu.
6menuTitle: Page Title # This allows you to set the menu title to be different from the page title.
7metaTitle: "A Meta Title | Handoff Design System"
8metaDesc: "A meta description"
9enabled: true # Setting this to false will hide a top level menu page
10menu: # An array of menu entries to display for all pages in this section.
11  - path: false # Setting the path to false makes a menu section
12    title: Menu Header
13  - path: path/file
14    title: Menu Entry
15    image: "zap" # A class name for an svg to display to the left of the menu
16---
17## Markdown Code
18This is a sample of how a markdown file can be added and will construct navigation
19in a site.  This file can include anything allowed in normal markdown.

Subpages are simpler since much of the menu and visibility is controlled by the parent page of the section.

subpage.md
1---
2title: A Page Title
3description: A page description
4metaTitle: "A page title | Handoff Design System"
5metaDesc: "A sample page in the Handoff Design System, in markdown"
6---
7This page could document the code standards and linting rules.

Add New Content

To add a new page, simply create a markdown file in the pages directory. Ensure that the markdown file matches the structure above.

For example, if you want to add a page to your site at /developer_guide you would create a file at /pages/developer_guide.md. This will create a top level menu entry that will point at /developer_guide.

If you want to add a subpage for something like Accessibility Standards, you would add a directory in pages called /pages/developer_guide and then add accessibility_standards.md to the directory. Your structure would look like this.

Page Structure
1pages/
2├── developer_guide.md
3├── developer_guide
4    └── accessibility_standards.md

Ensure that the menu of /pages/developer_guide.md looks like this -

Menu Structure
1menu:
2  - path: /developer_guide/accessibility_standards
3    title: Accessibility
4    image: "zap"

This will create two pages, a top level menu entry and a sub menu, with a single link. Note that you can make customize the secondary menu titles here.

Editing Existing Pages

All pages can be edited in Handoff. The following sections are editable through markdown - title, hero description, meta title, meta description, menu title secondary menu, and menu position.

To edit a page, look at the path of the page you want to edit. To edit a top level page, like Components, create a markdown file at /pages/components.md. We find it easiest to copy the existing page content as a starting point. - https://github.com/convertiv/handoff-app/src/master/docs/components.md

If you want to customize a section page, like /components/button, create a directory in your pages folder called button. Then find the default button markdown file in the repo https://github.com/convertiv/handoff-app/src/master/docs/components/button.md Copy that file to /docs/components/button.md and start customizing.

Hiding Existing Pages

To hide an existing top level page, set enabled: false. To hide a secondary page, customize the top level page for that section, and remove the menu entry from the menu list.

Customizing the Menus

To change the menu position of top level menu items, edit the page, and change the weight. Handoff orders the top level menu entries by weight, with heavier, higher weights moving down and to the right, and lighter, smaller weights moving up and to the left. Weights can be negative.

To change the menu text for top level menu items, edit the page and change the menuTitle value. This allows the menu title to be different from the hero title or metadata title.

To change secondary nav menus, edit the top level page of the section and customize the menu: array. You can create menus with and without paths allowing menus without paths to act as section dividers.

Default Pages

The following pages are created by default in Handoff:

Default Structure
1docs/
2├── assets
3│   ├── fonts.md
4│   ├── icon.md
5│   ├── icons.md
6│   └── logos.md
7├── assets.md
8├── changelog.md
9├── components
10│   ├── alert.md
11│   ├── button.md
12│   ├── checkbox.md
13│   ├── input.md
14│   ├── modal.md
15│   ├── pagination.md
16│   ├── radio.md
17│   ├── select.md
18│   ├── switch.md
19│   └── tooltip.md
20├── components.md
21├── design
22│   ├── colors.md
23│   ├── effects.md
24│   ├── logo.md
25│   └── typography.md
26├── design.md
27├── index.md
28├── styles
29│   ├── accessability.md
30│   └── standards.md
31└── styles.md