Skip to main content

Documentation Contribution Workflow

To contribute to the documentation (including blogs), you can follow the following guidelines for making documentation contributions.

All documents relevant to the project are written in the Markdown format. You can see the documentation for the GitHub Flavor here or you can use this quick guide.

All the documentation is visible on GitHub and https://pyrsia.io website, so it's important to keep in mind there are some limitations and extra features that might be available. You might want to refer to the website's standard features if you are unsure.

Structure Guidelines​

All the documentation for Pyrsia should live in the pyrsia/pyrsia repository in the docs folder. Blogs belong in the same repository but should be placed in the blog folder.

docs​

All sub-folders should have a readme.md with a good title, as a level one header, and the front matter for position the folder on the website. Make sure to pay attention to the other folder numbers.

All documents should have a .md file extension. If you need more customization you can use .mdx, see here for more information. All files need a level one heading to provide the page with a good title.

blog​

All blogs should be placed in the root of the blog folder. Each one should be named yyyy-mm-dd-<slug>.md, where slug should be a unique name for the blog (e.g. a short hand of the title); this is described here.

Some front matter is required at the top of the Markdown:

  • title
  • authors: [name, title, image_url]
  • tags

See #720 for an example.

In addition the draft front matter may be added so the blog can be reviewed by the community before being made public on the website.

Blogs should not have use a level one heading, after the fron matter the opening paragraph or abstract should be next. Section heading should begin with a level two heading.

All media assests should be external links since they will not be copied to the website when deployed from this repository.

Previewing Changes​

Currently it is only possible to preview your changes locally, you should be following the contributing guidelines and have forked the repository. To preview the changes:

  1. Fork the website's repository and clone your fork.
  2. Modify this line
    • Change pyrsia/pyrsia to your fork, (e.g octocat/pyrsia)
    • Optionally, you can change the branch by replacing main with your-branch-name
    • You can check this example
  3. Follow instructions described here for "local development"

If you make changes to your fork of the pyrsia/pyrsia repository, you can restart the local server to update the documentation. You can make changes locally and the local serve will automatically update; do not forget to change them to your fork afterwards.