Building a local preview
Because the documentation site is using a markup language instead of a WYSIWYG editor, the sources do not look exactly like the rendered page will. Therefore it is necessary to check that your changes look the way you want them to before you push and make a pull request. This involves building a local preview.
There are two shell scripts available in each existing repository (including the template repository used to create new content):
To preview, run the
build.sh script; this is the one that actually builds a local version of the site (or, more precisely, the subset of the full site that resides in your current repository). Then, run
preview.sh, which starts a webserver and serves the site at http://localhost:8080/. Opening this URL in any web browser will show you the preview, which will be available until you kill the process (kbd:[Ctrl+C] in the terminal).
To run the scripts you’ll need to install
If your work spans content in multiple repositories,
e.g. because you link to another repository,
you can extend the preview by adding more repositories to
site.yml as follows:
content: sources: - url: . branches: HEAD - url: https://pagure.io/fedora-docs/another-repository.git branches: main
Correct entries to use can be found from docs-fp-o site.yml.
If you want to use the regular Antora build and preview workflow - follow the instructions on Antora Documentation page.
Once you have
Antora CLI and
Antora Site Generator you can build and preview the pages without the container scripts.
To build the pages in the project directory run:
antora generate site.yml
This will create a new directory
public which contains all the necessary files. Navigate there and run a server command. You might already have a Python simple server, in which case run:
python3 -m http.server
or if you only have Python 2 on your machine:
python -m SimpleHTTPServer
It opens a local preview at port 8000.
If you have cargo (Rust package manager), you could also install and use
miniserve or any other simple server of your choice for that matter.
Want to help? Learn how to contribute to Fedora Docs ›