How to Contribute to the Threefold Manual
Table of Contents
Quick Method: Create an Issue
If you've found some issues or typos in the ThreeFold Manual, feel free to create an issue on the ThreeFold Manual repository to let us know. We will then be able to fix it as soon as possible.
The steps are simple:
- Go to the issues section of ThreeFold Manual repository on GitHub
- Click on
New Issue
- Choose an appropriate title
- Explain briefly the issue you found
- Click
Submit New Issue
Advanced Method: Create a Pull Request
If you found an issue in the manual and you wish to fix the issue yourself, you can always fork the repository and propose the changes in a pull request. We present the main steps in this section as well as further details on how to proceed efficiently.
Main Steps to Add Content
We present here the main steps to add content to the Threefold Manual by forking the repository threefoldtech/info_grid
to your own Github account.
- Go to the Threefold Manual repository: https://github.com/threefoldtech/info_grid
- Fork the Development branch
- On the top right corner, click
Fork -> Create a new fork
- On the top right corner, click
- Make changes in the forked repository
- Ask for a pull request
- In the forked repository, click
Contribute -> Open pull request
- In the forked repository, click
- Once the pull request is accepted, the changes of the Development branch will be available here: https://www2.manual.grid.tf
- The Threefold team will regularly update the Development branch to the Master branch
- The new content will thus be available here: https://www.manual.grid.tf
Note: You can update your forked repository by clicking Sync fork -> Update branch
.
How to View the mdbook Locally
Once you've forked the TF Manual repository to your Github account, you might want to see the changes you've made before asking for a pull request. This will ensure that the final output is exactly what you have in mind.
To do so, you simply need to clone the forked repository on your local computer and serve the mdbook on a given port.
The steps are the following:
- In the terminal, write the following line to clone the forked
info_grid
repository:-
git clone https://github.com/YOUR_GIT_ACCOUNT/info_grid
- make sure to write your own Github account in the URL
-
- To deploy the mdbook locally, first go to the info_grid directory:
-
cd info_grid
-
- Then write the following line. It will open the manual automatically.
-
mdbook serve -o
- Note that, by default, the URL is the following, using port
3000
,http://localhost:3000/
-
- You should now be able to see your changes.
How to Install git and mdbook
To install git, follow the steps provided here.
To install mdbook, you can download the executable binaries available on the GitHub Releases Page. Simply download the binary for your platform (Windows, macOS, or Linux) and extract the archive. The archive contains an mdbook executable which you can run to build your books. To make it easier to run, you can put the path to the binary into your PATH.
For more information, read the mdbook Documentation.
Markdown File Template (Optional)
Here are some suggestions on how to organize a Markdown file (.md
) when you submit contents to the ThreeFold Manual. This is not necessary, but it will ease the whole process.
- Title: Heading 1 (
#
in Markdown syntax) - Main sections: Heading 2 (
##
in Markdown syntax) - For Markdown files that contain a Table of Contents:
- Use
<h1>
instead of#
for the Title , and<h2>
instead of##
for the Table of Contents.- This quickens editing when creating and updating the ToC (read this for more details).
- Other heading labels should use standard Markdown headings (
##
, etc.).
- Use
- If your text reaches heading level 4, you might want to separate your file into two or more files.
- A long article can be spread in many subsections.
Questions and Feedback
If you have any questions or if you would like to share some feedback, let us know in this Threefold forum post.