docs/modules/ROOT/pages/index.adoc

partial$attributes.adoc

The Pizza Project

The Pizza Project is a useful project with a very bad name — it’s just what’s in our template repo to show off some basics.

In fact, this is just a source template for a new piece of the Fedora Docs.

Below is some hopefully useful info about how to work with this stuff.

Antora & ASCIIDoc basics

• This whole section is a list, hence the points.

• Below is an image. The image source is located in modules/ROOT/assets/images. See the source for how it’s inserted.

  

  Notice that the image is a part of the same "list item" as the sentence above it; that’s due to the ` on newlines, if you delete that and refresh the page, it'll move slightly to the right. That's not really relevant to an unordered list like used here, but you'll need it if you want to make a numbered list with a multi-paragraph list item. The ` sign joins multiple paragraphs (or other block elements like images or that "Tip" box below) into one item.

  You can also make some changes to how images are displayed, like set width/height, scaling, alignment, even turn one into a link. See here for available attributes: ASCIIDoctor Docs. These options are all, well, optional.

• You can also add images inline (as part of a paragraph of text), but that’s rarely useful. If you ever need to do that, just use one colon instead of two in the image: declaration and put it into a paragraph. It never looks good though.

• Last updated in {year}. Notice how in the page source, the sentence used the attribute {year} instead of just saying 2022. The attribute is defined in modules/ROOT/assets/partials/, there is also an example file that explains this further. Don’t forget to include the attributes file on top of the page if you want to use these.

• To link to another page in the same repository, instead of using a hard link:<url>[<text>] (used for outside links), use an xref instead. For example, to link to the Architecture page, use xref:architecture.adoc[Architecture], which results in this: Architecture. The navfile (nav.adoc) uses those as well, check it out and look how it works. (Also note how you can add multiple levels to the list). It’s also possible to use this to link to another repo that’s published on Docs.FP.O, but that gets more complicated. Ping me if you ever need to do that.

• Each page needs to start with a top level heading, preceded by = (like this one). Any subsequent headings then have a number of equals signs which determine their depth. These will automatically show up in a table of contents that’s automatically generated on the right.

Tip	Other than that, you might find a [TIP] infobox like this useful. You can also use [CAUTION] and [WARNING] if you need to, they have different border (purple and red).

• Inserting a code block works like this:

  $ dnf install podman -y

  Optionally you can specify which language it’s using to set the correct keyword highlighting; to do that, add a keyword specifying the language immediately after the "source" keyword. Like this: [source,bash] - I can’t remember where the full list of keywords was, but if you ever need it, ping me and I’ll try to dig it up.

• Any new pages you write should go into the modules/ROOT/pages directory and have the .adoc file extension. Then, you also need to add the file to the modules/ROOT/nav.adoc file; if you don’t, they will still exist, but they will only be accessible if you know their exact URL. Of course, deleting pages (like the weird stuff currently in the repo) works the same way, if you delete something, delete both the file and the entry in nav.adoc.

• The modules/ROOT/pages directory can have subdirectories, called topics. This may be useful if you find that there are multiple self-contained areas of docs with a lot of pages and you want to keep them separate so the repo is easier to work with. In that case, you can just make subdirectories in pages/, and when you’re using an xref, add the topic subdirectory into the path (for example, xref:other_topic/page_name.adoc[A page in the other_topic directory]). If the repo isn’t too big it’s easier to just not bother with subdirectories.

• Use the docsbuilder.sh script in the root of this repo to run a preview - just open a terminal, point it at the repo root, and run ./docsbuilder.sh. You’ll need to have podman and inotify-tools installed. If there’s anything else you need, the script will tell you with an error message. The README.md in this repo explains how it works.

• Finally, for the actual writing: Here’s our docs guide, go through the Writing Contributions to Docs, especially the markup section. A decent list of syntax for commonly used elements (lists, etc.) is in the ASCIIDoc Syntax Quick Reference.