Tutorials
###Adding-tutorials
Tutorials are a great way to teach people how to use your project. They are a step-by-step guide that walks the user through a specific task or concept. Tutorials are a great way to get people up and running with your project, and to help them understand how to use it.
How tutorials are written
Tutorials are written in Quarto markdown. Quarto is a markdown language that is designed to be easy to write and read, and to be easy to convert to other formats. Quarto is a superset of markdown, so any markdown file is a valid quarto file. Quarto adds a few features to markdown to make it easier to write tutorials. Some of the features include:
- The ability to include code and output in the same file
- The ability to include code from other files
- Adding metadata / images and other content to the file
Folder to write the tutorial
By default, tutorials are written in the /tutorials
folder. This is the folder where all the tutorials are stored. Each tutorial is stored in a separate folder, and the folder name is the name of the tutorial. Inside the folder, there are serveral .qmd
files that contains the tutorial contents.
Configuring the tutorial
There is also a config.json
file that contains the configuration for the tutorial. The config.json
file is used to structure how the tutorial is displayed in terms of the order of the tutorial, the title, the description, and the grouping of the tutorial.
Below is an example of a config.json
file:
{
"contributing": {
"title": "Contributing to the project",
"children": {
"improving_documentation": {
"title": "Improving documentation"
},
"raising_issues": {
"title": "Raising issues"
},
"raising_pr": {
"title": "Raising pull requests"
}
}
},
"project_structure": {
"title": "Project structure"
},
"environment_setup": {
"title": "Environment Setup"
},
"changelog": {
"title": "Change log"
},
"localization": {
"title": "Localization"
},
"how_to": {
"title": "How to's",
"children": {
"setting_default_readme": {
"title": "Setting default README"
},
"adding_tutorials": {
"title": "Adding tutorials"
},
"specifying_source_files": {
"title": "Specifying source files"
},
"starting_a_new_build": {
"title": "Starting a new build"
}
}
}
}
In the example above, the config.json
file contains a list of tutorials and the order in which they should be displayed. The config.json
file also contains the title of the tutorial and the description of the tutorial.
The config.json
file also contains a list of children for each tutorial. This is used to group tutorials together. For example, in the example above, the contributing
tutorial has three children: improving_documentation
, raising_issues
, and raising_pr
. This groups the three tutorials together under the contributing
tutorial.
Grouping tutorials
Tutorials can be grouped together using the config.json
file. This is useful for organizing tutorials into categories. For example, you might want to group all the tutorials related to contributing to the project together, or all the tutorials related to setting up the environment together. This makes it easier for users to find the tutorials they are interested in.
In the example above, the config.json
file groups the tutorials into categories such as contributing
, project_structure
, environment_setup
, changelog
, localization
, and how_to
. Each of these categories contains a list of tutorials, and each tutorial contains a list of children. This allows you to organize the tutorials in a way that makes sense for your project.
In this tutorial, we learned how to write tutorials in Quarto markdown, and how to configure the config.json
file to structure how the tutorial is displayed. We also learned how to group tutorials together using the config.json
file. This allows you to organize the tutorials in a way that makes sense for your project, and makes it easier for users to find the tutorials they are interested in.
Summary - How tutorials are written - Format for writing tutorials - How to write a tutorial - Folder to write the tutorial