Adding new documentation to the site
This section describes how to add new documentation to the website and ensure it is published and listed somewhere. Before you start following this procedure, make sure that you fulfill all the requirements lited in Prerequisites.
|== Before you start creating an entirely new documentation set, consult the mailing list to make sure your work is accepted by the project and you do not spend time developing docs that will be rejected in the end. ==|
Clone the template repository: https://pagure.io/fedora-docs/template
Create a new pagure repository for the new documentation set, or ask someone to create one for you. The new repository should be listed under
Clone the newly created repository for your content set.
Copy the contents of the template repository (without the
.gitdirectory) into the newly created repository.
In the new repository, edit the
antora.ymlconfiguration file in the repository root. The file contains comments that point out which parts you need to change. At a minimum, always change the
Additionally, edit the
site.ymlconfiguration file. Note that this file is only used when building a local preview of your content set - on the website it is overriden by the sitewide
site.ymlconfiguration. The only directives you need to edit in this file is the
At this point, when the initial configuration is finished and the repository is configured with the correct name and other required directives, push these changes to the newly created repository (or make a pull request if you can not push directly). This set of changes will be required for any other contributions, so make sure they are in as early as possible.
Fork the new repository, so you are not pushing updates directly into it.
Start adding the actual ASCIIDoc content. While writing, make sure files your new source files are included in the
nav.adocconfiguration file of the module you are using (
./modules/ROOT/by default, the location will change based on what you configured in
antora.ymlearlier). Also make sure to use local preview often to check your markup.
Once you finish, commit your changes and push them to your fork.
Use pagure to make a merge request from your fork to the main repository’s master branch.
Someone will see your merge request and either merge it, or provide feedback if there is something you should change. Work with the people commenting to make sure your contributions are up to standards.
Your new content will need to be published for the first time, and at the moment this does not happen automatically. Send an e-mail to the docs mailing list asking for your content to be published.