Creazione di un’anteprima locale
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 |
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 ›