Skip to content

Latest commit

 

History

History
62 lines (41 loc) · 3.7 KB

README.md

File metadata and controls

62 lines (41 loc) · 3.7 KB

Ombi.Docs

Docs Site: https://docs.ombi.app
Doc Deployment

This is the source repository for the Ombi Docs site. It replaced the old wiki with something a little more... professional.

If you'd like to get involved with the project, reach out on discord.


Setting up a dev environment

The easiest method to install mkdocs is via python - it's consistent across different OS environments.
Install Python for your OS, ensuring that it gets added to PATH.

Once you have Python installed, you'll need to clone the repository and install the python packages used by this site (like mkdocs itself). To do this, clone the repo, and from the relevant terminal/shell/prompt, change directory to the repo folder and run
pip install -r requirements.txt
to ensure you have all the relevant packages for use.

Editing the site

To edit the site content, edit the markdown files under "docs".
To edit the site layout, edit the mkdocs.yml file (held in the root directory).
If you are working on changes, use the development branch in this repo as a base, and create a branch with your suggested changes.

Note that the new documentation repository is not directly publicly editable - for a few reasons, including (but not limited to):

  • Markup (as used in mkdocs.yml) is an indent-sensitive language.
  • Markdown (what all the pages themselves are written with) has defined standards.
  • We'd like to be able to validate content before it gets put into official documentation (the old wiki had a lot of inaccurate community-submitted content).

As such, all edit requests will need to go through approval by submitting a pull request.
All PRs need to target the development branch of the docs, to allow for merging of formatting for consistency.

Suggested editor

VS Code is a good option to use for editing this content, as it has extensions for markup and markdown syntax highlighting (as well as preview functions).
Included in this repository is a workspace config for vscode with some defined spelling, linting, and error-checking methods, as well as a group of recommended VS Code extensions for use.
Atom is another good option.

Using mkdocs

The site is being built using mkdocs, which converts standard markdown to static html.
mkdocs itself can be told to 'serve' the folder by opening the folder containing mkdocs.yml in your relevant console/terminal and running mkdocs serve.
This will let you live preview the site in your browser, with changes being updated any time you save an edit to a file.

mkdocs references

Source reference:

Example Configs