Creazione di un’anteprima locale

Team di Documentazione di Fedora https://discussion.fedoraproject.org/tag/docs Last review: 2023-03-19
Un’anteprima locale è uno strumento prezioso per testare le modifiche mentre lavori nel tuo ambiente di scrittura locale. Esegui lo script docsbuilder disponibile nel repository dei contenuti di Fedora. Puoi costruire ed eseguire il sito completamente renderizzato sulla tua macchina per visualizzare in anteprima le modifiche prima di effettuare una full request ai repository dei contenuti Fedora.

Quando hai bisogno di un’anteprima locale

Quando lavori con un ambiente di scrittura locale, un’anteprima locale offre un flusso di lavoro versatile per testare come le modifiche verranno visualizzate e funzioneranno nel tuo browser in locale. Quando apporti modifiche come, ma non solo;

  • Modificare i link o correggere i link rotti

  • Change document to document cross references using xref

  • Consolidate multiple pages into one page

  • Aggiornare le immagini o correggere le immagini non funzionanti

  • Add metadata or alt text for images

  • Section levels reorganized (Example: h2 to h3, h3 to h4) for readability and reading flow

  • Fix inactive navigation bar

  • Reorganize navigation bar

  • Rewrite outdated pages

  • Add AsciiDoc attributes

  • Reiterate changes and tests with vale linter

you need build scripts to render the changes predictably and test them before you make a pull request.

What the scripts do

A unified docs builder script, docsbuilder.sh, builds a local version of the site, which means the subset of the full site that resides in your local repository. In turn, the script starts a webserver and serves the site at http://localhost:8080/. Opening this link in any web browser will show you the preview, which will be available until you kill the process (kbd:[Ctrl+C] in the terminal).

Check README.md on the landing page of projects to run the script suggested to use.

How to test changes

Go to the the directory where cloned repo is, build, watch and preview the site by running the build scripts in terminal.

$ ./docsbuilder.sh

Pagure or other content repositories display a different builder script.

$ ./builder.sh

To use the scripts you need Podman installed if using Fedora Linux or Docker CE if using macOS.

Previewing multiple repositories

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.

Using the regular Antora scripts

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 ›