Community Contributions Guide¶
The RIT Documentation website is hosted on GitLab Pages and uses mkdocs plus the Material theme. You can browse its source code, fork it, and create a merge request if you'd like to contribute some changes.
For RIT staff, please see our internal docs to learn how to make changes to the site.
Below we provide some brief tips for working with mkdocs. For full documentation visit mkdocs.org.
mkdocs new [dir-name]- Create a new project.
mkdocs serve- Start the live-reloading docs server.
mkdocs build- Build the documentation site.
mkdocs help- Print this help message.
mkdocs.yml # The configuration file. docs/ index.md # The documentation homepage. ... # Other markdown pages, images and other files.
All internal links (meaning they point to somewhere on the same domain) in an
mkdocs site must be relative. This means that when adding the link you should use
.. to mean go back one directory. For example, if you're working on the page at
docs/services/high-performance-computing/user-guide/storing-data.md and you want to link to the page at
docs/services/high-performance-computing/getting-help/index.md, you can write the link as:
<a href="../../getting-help/">Getting Help</a>
Note that the first
.. corresponds to the directory
docs/services/high-performance-computing/user-guide/, and the second takes us back one more level to
docs/services/high-performance-computing/. If we were creating a link in the
index.md file of the
user-guide/ directory instead of the
storing-data.md file, then
.. would instead correspond to
docs/services/high-performance-computing/ rather than
Redirects for old URLs¶
If you change the URL of a page or remove a page, you can put a redirect into
mkdocs.yml. Just look for the redirects stanza and follow the examples there. The format is "services/...../old_path.md: services/....../new_path.md"
Q. What is the meaning of life, the universe, and everything?
To achieve the above style, the syntax is:
??? question "Q. What is the meaning of life, the universe, and everything?" 42
??? questionand the answer goes below the question. Note that the answer must be indented using 4 or more spaces, and all lines until the first non-indented line will be included in the answer box.