egret/team-docs
1
0
Fork 1
forked from docs/team-docs
Code Pull requests Wiki Activity

Shorten README

Browse source 
I've shortened this README based on what we came up with in this issue: docs/tickets#36 (comment)
This commit is contained in:
Jonas Hubeny 2026-06-03 20:09:24 +00:00
commit 16595b12e5
1 changed files with 17 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

79
README.md
View file

@ -1,70 +1,25 @@
# Fedora Docs documentation
# Fedora Docs Team Documentation
This repository contains a minimal source structure for a new Fedora Docs source.
Team and contributor documentation for the Fedora Docs Team.
## Content of this repo
## Published documentation
### Fedora Docs docs (placeholder)
The published version of this documentation is available at:
[https://docs.fedoraproject.org/en-US/fedora-docs/](https://docs.fedoraproject.org/en-US/fedora-docs/)
Under `modules/ROOT`, a placeholder for the Fedora Docs docs — intended to be moved to its own repository.
## Contributing
### Fedora Docs docs / contributing
We welcome contributions! Whether it's fixing a typo, reporting an outdated
page, or writing new content — every little bit helps.
Under `modules/contributing`, the contributor's guide — the primary content of this repository.
See the [Fedora Docs Contributor Guide](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/)
for how to get started.
## Structure
Please report **content issues** in this repository.
For general site/publishing issues, use the
[Fedora Docs Website repository](https://forge.fedoraproject.org/docs/docs-fp-o).
```
|-- README.md
|-- antora.yml ....................... 1.
|-- build.sh ......................... 2.
|-- preview.sh ....................... 3.
|-- site.yml ......................... 4.
`-- modules
`-- ROOT ......................... 5.
|-- assets
| `-- images ............... 6.
| `-- ...
|-- nav.adoc ................. 7.
`-- pages .................... 8.
|-- ...
```
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.
## Components and Modules
Antora introduces two new terms:
* **Component** — Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Project, Fedora council, Mindshare, FESCO, but also subprojects such as CommOps or Modulartity.
* **Module** — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories.
## 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](https://gitlab.com/fedora/docs/-/boards) for instructions.
Both scripts use docker, so please make sure you have it installed on your system. Please see below for instructions.
To build and preview the site, run:
```
$ ./docsbuilder.sh
```
The result will be available at http://localhost:8080
### Installing docker on Fedora
```
$ sudo dnf install docker
$ sudo systemctl start docker && sudo systemctl enable docker
```
## Contact
- **Matrix:** [#docs:fedoraproject.org](https://matrix.to/#/#docs:fedoraproject.org)
- **Private comms:** Use our FAS emails for anything that shouldn't be public.
- **Discussion forums:** [discussion.fedoraproject.org](https://discussion.fedoraproject.org/tag/docs-team/337)