design/docs
16
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

First update

Browse source
This commit is contained in:
emma kidney 2025-02-13 16:37:45 +00:00
commit 88bb83fb50
6 changed files with 129 additions and 143 deletions
Download patch file Download diff file Expand all files Collapse all files

53
modules/ROOT/pages/index.adoc
View file

@ -1,53 +1,30 @@
include::partial$attributes.adoc[]
include::ROOT:partial$attributes.adoc[]
= The Pizza Project
= Fedora Design
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.
== About Us
In fact, this is just a source template for a new piece of the Fedora Docs.
The Fedora Design Team is Fedora's in-house design agency. We provide artwork, user experience, usability, and general design services to the Fedora project.
Our current team goals:
Below is some hopefully useful info about how to work with this stuff.
== Antora & ASCIIDoc basics
* *Template and Automate* - Generate templates, standards, and automation where possible for more efficient and consistent artwork production.
* 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.
+
image::image$pizza.png[Pizza]
+
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: link:https://docs.asciidoctor.org/asciidoc/latest/macros/image-ref/[ASCIIDoctor Docs]. These options are all, well, optional.
* *Increased focus on UX/usability* - Increase the amount of UX and usability work we provide to the Fedora project through both more efficient usage of current designer time and also better recruitment of UX/usability team members and better documentation of UX/usability tasks and processes.
* 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.
* *FLOSS Creative Tool Education & Outreach* - Continue to use the very same free and open-source creative tools available in Fedora to design for Fedora, and increase and improve knowledge sharing with the general FLOSS community.
* 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: xref:architecture.adoc[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.
* *Clear Priorities* - Strive to be more selective about our focus as a team and set clear priorities so the things that are most important to Fedora are done in a timely and organized manner.
[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).
====
== Join Us
* Inserting a code block works like this:
+
[source]
----
$ 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.
We're always looking for new members. Join the design team and:
* 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`.
* Build your portfolio by working on real-world projects
* Learn open-source design tools from experts - never pay for Creative Suite again!
* Work with awesome designers from around the world
* 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 link:https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/[docs guide], go through the Writing Contributions to Docs, especially the link:https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/asciidoc-markup/[markup] section. A decent list of syntax for commonly used elements (lists, etc.) is in the link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[ASCIIDoc Syntax Quick Reference].
//Yes, I just used a hardlink to another docs repo instead of an xref. Also this is a comment, it won't be displayed on the page but you can use it for TODOs and such.
To learn how to join Fedora Design Team, please see the xref:getinvolved.adoc[Get Involved] page.