Handbook Development
Development environment and processes for maintaining the handbook
Contributing Guidelines
General
- Child pages of a section and their summary are automatically listed at the bottom of each section page.
- Pages can only be authored as
.htmlor.mdand you should use only one file extension or the other. Instead of creatingmy-team/about/index.html.mdsimply usemy-team/about.md.
Section Pages
Section pages (_index.md) are a bit special. If you are creating a new section (a directory that will have
child pages), you should always include a _index.md in the same directory. By default, the bottom of your “section”
age will include a list of child pages within the section. See as an example.
Content Structure
Below is an example of the content structure used for this site:
content
├── docs
│ └── _index.md
├── handbook
│ ├── alliances
│ │ ├── _index.md
│ │ ├── aws.md
│ │ ├── ecosystempartners.md
│ │ ├── gcp.md
│ │ ├── ibm.md
│ │ └── redhat.md
│ ├── company
│ │ ├── _index.md
│ │ ├── communication
│ │ │ ├── _index.md
│ │ │ └── project-code-names.md
│ │ ├── crisis-process.md
│ │ └── performance-indicators
│ │ ├── _index.md
│ │ ├── product
│ │ │ ├── _index.md
│ │ │ ├── dev-section.md
│ │ │ ├── enablement-section.md
│ │ │ ├── modelops-section.md
│ │ │ ├── ops-section.md
│ │ │ ├── sec-section.md
│ │ │ └── stages-and-groups.md
│ │ └── sales.md
│ └── ...
Under Construction
Contributing guidelines are WIP. If you are feeling ambitious here are some useful links:
Development
Continue reading in the development section
Handbook frontmatter
Information on what frontmatter entries are available and how to use them.
Handbook Markdown Guide
Read through our Markdown Style Guide!
Partials
Hugo partials are bits of reusable content. They’re primarily used for parts of theme files, other HTML (such as layout) files, and within shortcodes.
Partials may exist in the theme for use on all content sites, or in a specific repository, such as the handbook. Many partials are duplicated, sometimes with minor edits, in the handbook projects.
When deciding which to create, if the reusable content is meant be used only in Markdown files,
create a shortcode instead.
Partials are easy to make, so many have been created without documentation.
If you encounter a partial that is not listed, please look for the merge request that introduced it to ask the creator to document it,
or ask in the #handbook Slack channel.
Shortcodes
Shortcodes are pre-defined ways to display content in Markdown files. If something looks somewhat like a shortcode, but starts with “partial”, then it’s a partial.
The shortcodes are listed alphabetically after the shortcode explanatory sections.
Shortcodes are easy to make, so many have been created without documentation.
If you encounter a shortcode that is not listed, please look for the merge request that introduced it to ask the creator to document it,
or ask in the #handbook Slack channel.
