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 docs/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