Creating Docs Pages

Creating Docs Pages

All pages on this site are hosted in the Momentum Mod docs GitHub repository. The site uses Hugo with the Hugo Book, and is entirely open source.

Content on the site is written using Markdown, a simple and lightweight markup language. This allows docs pages to be written in a much more accessible format than HTML.

If you’re having trouble with any parts of this guide, please feel free to ask for help in the #docs channel on our Discord. It’s completely fine if you’ve not used a command line or Git before, we’re happy to help you through the process.

Setting up Locally #

The two prerequisites for local development are:

For Windows users #

If you don’t have a preferred package manager, Winget now ships with Windows and should be able to handle everything for you. Open a terminal as administrator, and run

winget install Hugo.Hugo.Extended

If you don’t have a preferred terminal setup already, we highly recommend use either of these, and not cmd.exe:

  • Powershell (which ships with Windows) or
  • Git Bash (which you can install as part of the Git for Windows setup from the above Git download page).

Then, clone the repo with

git clone --recurse-submodules https://github.com/<github name>/<fork name>

Using Git is beyond the scope of this guide, and well-covered elsewhere. If you’re new to Git, we recommended this guide by Github.

Follow that guide up to the end of the Creating a branch to work on section, then check out the below content. Once you’re finished making your changes, see the rest of the guide for how to commit and pull-request them.

With your fork cloned locally, within the docs directory in your terminal (you made need to run cd docs if you’ve just cloned) run:

hugo server

This will build the docs and host them on a local server at http://localhost:1313. As you make changes to the docs, Hugo will automatically rebuild and refresh the browser window.

When you are finished making changes, press Ctrl + C in the terminal to shut down the Hugo server.

Creating a new page #

Pages exists inside the content/docs directory. To create a new page, make a markdown file in its relevant subsection. For example, the markdown for this current page lives in content/docs/guides/create-docs-page.md.

Markdown #

The essential content of all pages is in Markdown. Specifically, Hugo uses this package. We won’t provide a specific markdown guide here, as there are numerous resources online. Here’s a useful cheat sheet that should cover everything needed for contributing here.

Front Matter #

All pages begin with something called the “Front Matter”. This is YAML markup used to express metadata about the page, demarcated using ---. For example, here’s the front matter for this page:

---
title: Creating Docs Pages
categories:
  - guide
tags:
  - meta
  - contributing
---

title #

The title property denotes the title of the page, displayed at the top of the page and used in the menu and other parts of the site autogenerated by Hugo.

For templating reasons we insert the title value at the top of the page automatically. You do not need to add a title explicitly in markdown!

categories #

The broad section of the docs the page is related to, typically this in the same as the directory name the page lives in, and one of guide, command, var, entity.

Technically, a page can have multiple categories (hence being named categories not category), but this is just a Hugo thing. In practically all cases, a page only needs to have a single category.

tags #

A list of tags that apply to the page. Try to think of tags that apply to this and similar pages (can always look at the tags used by similar pages), just don’t use anything overly broad like “momentum” or “var”.

weight #

Controls the position of the page in the side menu. The lower the weight, the higher on the menu. Pages with equal or no weights are ordered alphabetically.

long_title #

Overrides the value of title used at the top of the page. For when a page should have a longer title on the page itself, but use title in the menu.

requires_mapping #

If true, displays a warning at the top of the page that the -mapping launch option is required. (will be removed in the future when -mapping mode is removed)

command only: safeguard #

Links to a corresponding run safeguard convar.

command only: required_params #

Displays a list of required params to use with the command.

command only: optional_params #

Displays a list of optional params to use with the command.

var only: minimum_value #

Minimum value of the convar the page is for.

var only: maximum_value #

Minimum value of the convar the page is for.

var only: default_value #

Minimum value of the convar the page is for.

entity only: tool_texture #

Informs about a specific tool texture that must be used with the brush entity.

Shortcodes #

Shortcodes are sections of markdown that Hugo applies specific formatting to. We do not allow raw HTML, if specific formatting is needed, it should usually be a shortcode.

Hints #

You can highlight something that’s important by prepending a notice tag like so:

{{< hint danger >}}
I'm red!
{{< /hint >}}

is displayed as

I’m red!

likewise,

{{< hint info >}}
This one is blue
{{< /hint >}}

is displayed as

This one is blue

and

{{< hint warning >}}
This one is yellow
{{< /hint >}}

is displayed as

This one is yellow

Refs #

As a convenient way to reference other pages using minimal markdown, we include shortcodes called cmdref, varref, entref and guideref. For example, for the mom_restart command, use

{{< cmdref mom_restart >}}

img #

You can apply specific CSS styling to <img> elements using {{< img style="CSS STYLING" src="IMAGE SOURCE" >}}

color #

You can apply specific CSS color codes to text using {{< color >}}. E.g. {{< color color="lightgreen" text="green" >}} renders as green .

Others #

Our theme, Hugo Book, includes some other shortcodes we don’t currently use, which can be found here.

Contributors needing custom shortcodes for other reasons are welcome to create new ones, just please add mentions of them to this section.

tag-outline Tags: meta contributing
folder-open-outline Categories: guide
Calendar May 5, 2023
Edit Edit this page