README.md

Fedora Magazine docs

This repository contains sources of the Fedora Magazine documentation.

Technical information

|-- README.md
|-- antora.yml ....................... 1.
|-- build.sh ......................... 2.
|-- preview.sh ....................... 3.
|-- site.yml ......................... 4.
`-- modules
    `-- ROOT ......................... 5.
        |-- assets
        |   `-- images ............... 6.
        |       `-- pizza.png
        |-- nav.adoc ................. 7.
        `-- pages .................... 8.
            |-- index.adoc
            |-- page.adoc
            `-- another-page.adoc
  1. Metadata definition.
  2. A script that does a local build. Uses docker.
  3. A script that shows a preview of the site in a web browser by running a local web server. Uses docker.
  4. A definition file for the build script.
  5. A "root module of this documentation component". Please read below for an explanation.
  6. Images to be used on any page.
  7. Menu definition. Also defines the hierarchy of all the pages.
  8. Pages with the actual content. They can be also organised into subdirectories if desired.

Local preview

This repo includes scripts to build and preview the contents of this repository.

NOTE: Please note that if you reference pages from other repositories, such links will be broken in this local preview as it only builds this repository. If you want to rebuild the whole Fedora Docs site, please see the Fedora Docs build repository for instructions.

Both scripts work on Fedora (using Podman) and macOS (using Docker).

To build and preview the site, run:

$ ./build.sh && ./preview.sh

The result will be available at http://localhost:8080

Installing Podman on Fedora

Fedora Workstation doesn't come with Podman preinstalled by default — so you might need to install it using the following command:

$ sudo dnf install podman