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.
All the documentation for Pyrsia should live in the pyrsia/pyrsia repository
docs folder. Blogs belong in the same repository but should be
placed in the
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
here for more information. All files need a level one heading to provide the
page with a good title.
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:
- authors: [name, title, image_url]
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.
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:
- Fork the website's repository and clone your fork.
- Modify this line
pyrsia/pyrsiato your fork, (e.g
- Optionally, you can change the branch by replacing
- You can check this example
- 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.