Discussing Fedora Docs website improvement

In this case you can ignore my last post :partying_face:

Yesterday, I deployed the latest version of the search extension, which brings us a few improvements like a reduced index size (it’s a little less than 4MB now) and more contextual information in the results:

You’ll also find a checkbox allowing you to search only within the current doc component.

1 Like

According to my impression it is very fast now. Is the index file loaded in the background when the page is loaded? Or is the loading started when you perform a search?

1 Like

It’s loaded in the background. You can see it if you look at the search bar, it’s disabled at first when you load the page (grayed out) until the index is in memory.

1 Like

Today, I pushed 2 new asciidoc related improvements for doc writers:

  • RPM Spec highlighting
  • Datatables support

RPM Spec highlighting


Name:		hello
Version:	2.10
Release:	1%{?dist}
Summary:	The "Hello World" program from GNU
Group:		Unspecified
License:	GPLv3+
URL:		https://www.gnu.org/software/hello/
Source:		https://ftp.gnu.org/gnu/%{name}/%{name}-%{version}.tar.gz

BuildRequires:	gettext

The GNU Hello program produces a familiar, friendly greeting.


Convert table to DataTables (https://datatables.net) using the datatable role attribute.
Can be useful for big tables, if you need data filtering/ordering.
Additional roles can be used to add DataTables features:

  • dt-search: add search box
  • dt-paging: add pagination

You can also alter the styling with the help of built-in DataTables classes, such as display or compact.

Usage examples:
Load csv file into a table and enable the search feature.

.Statistics per component

Apply classic DataTables styling with display role.

|colA | colB | colC | colD

| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
| ccc | 9 | ttt | 2%
| aaa | 987 | www | 18%


What are we up to lately?

First, I introduce the new top nav bar used in our upcoming new Fedora websites. This is not the final version, but more an early preview of what’s coming next.


Next is the revision information you can find just below the title, with the authors’ details, revision date, and version.
We can use that information to quickly check if the document has been reviewed for the last version, and when.

New admonitions style, thanks to @likeanushkaa !

Like the nav bar, the footer has been reworked to match the future design used in new Fedora websites.

And last, but not least, darkmode, matching your OS preferences:


The changes previously mentioned have been pushed to the staging environment for review:

Feedbacks are welcome.


This is very trivial, but I think the color of the tiles for Fedora Linux, Fedora Server, Fedora Council etc. is very dark. The color design of the new website feels more “light” to me, personally. I reckon the tiles could be a lighter color, but I don’t have a strong feeling about it. Just some feedback.

I like that very much. 2 Questions:

  1. Originally, we planned to have “Fedora Linux” and “Quick Docs” in the top row, with “Fedora Linux” being 2 tiles in width and “Quick Docs” 1 tile. So it should grow and shrink in 2:1. That doesn’t work in the current CSS. Could we get it fixed on this occasion?

  2. Some users noticed that the icons to edit a page or to create an issue can easily be overlooked. Can we improve that, e.g. by color or a bigger size (but that could decrease the elegance)

1 Like

The homepage is basically pure HTML. You can set whatever classes/styles you need on it.
For instance, you could add style="flex-basis: 600px;" to the Fedora Linux item, and it’ll make it bigger.

I don’t have any solution to that right now but I’m open to suggestions :slight_smile:


Yes, but I think we should use the same CSS as all the other pages to ensure consistency. We may overwrite styles that are specific for the boxes page. But we shouldn’t touch basic elements. E.G. we should change the principal construction the boxes, e.g. using margin or not" Or are the boxes specific for docs start page and never used somewhere else?

We need a fluid design, so we can’t use px. I tried to use a growth ratio for the flex boxes, but it didn’t work as expected. Do you know a css expert we can ask?

That’s true. But consistency is not the issue as all the CSS on this page is very specific to this single page. We don’t have any other page in the documentation that uses this layout.
I also don’t really want to spend too much effort on tweaking this page since we are most likely going to rewrite it entirely at some point in the future.

I’m not a CSS expert, so please forgive me, but I’m not sure why using a px value with flex-basis is an issue with fluid design. We are already using a px value anyway for this exact same attribute (which is currently set to 300px).
If you really don’t want to use px, you can use a percentage, like 33% / 66% (minus the margin).

1 Like

Do you have an idea what that means in terms of months / years / decades? And do you watch the discussion? I’m a bit unhappy with the current revamp of some pages. A great graphic design, but at times sparse information and lacking substance.

Our current page may look a bit old-fashioned, but compared to other distributions, it provides a good overview and a lot of significant information. I would like to preserve that very much.

Nor am I. It’s been a while since I’ve implemented a design in CSS. Anyway, if we’re pretty independent here, we can tackle it if we need to. We can keep it as is as long as we don’t have to add boxes for new issues or anything like that.

Dark mode toggle on top right is chef’s kiss. Contrast and visibility of future site are much more enhanced than AS-IS.

The new UI is now deployed in the production environment.

Our asciidoc documentation has also been updated with the latest changes.


I am resurrecting this older thread for 2 issues.

If you collapse the Docs Pages very narrow (e.g. a smartphone). then the TOC pushes itself between the title line and the author line. Usually will be between the author’s line and the first content line.

We discussed making the icons for editing and issue creation more visible. But we didn’t know how to design and to achieve that.

I would propose to enlarge the horizontal space between the icons and the language selector. This alone would make them more visually striking.

Additionally, I would suggest coloring the icons with the blue of the header bar. This increases the visibility further, but keeps the design character and elegance of the theme.

I hope neither is too much work.

1 Like

I pushed a new update with the following fixes & features on the prod documentation website:

  • added category system for quick docs (example)
  • fixed font size for h4 heading
  • fixed alignment issue in admonition blocks on Chrome
  • removed automatic hyphens from code blocks
  • fixed the embedded TOC position in mobile view

@pboy: I believe (1) should be fixed by now. Can you open a ticket in the documentation UI repo for (2)? It will be easier for me, or anyone else who wants to contribute, to keep track of those issues.



And No1 is fixed. Great!

1 Like

Today, I pushed a few minor changes in production, added by @ferdnyc.
Among them, the most notable one is the copy-to-clipboard button for code blocks (upper right when hovering):

Check the clipboard button on the upper right

There is also a special console codeblock that makes copy-pasting easier for command lines:

$ mkdir example
$ cd example

or using a literal paragraph (lines starting with a space):

 $ mkdir example
 $ cd example

In both cases, lines starting with $ are joined with && and the $ is removed.
From the previous example, the pasted text will become:

mkdir example && cd example

This also works with long split lines:

$ podman run -v $PWD:/antora:Z --rm -t antora/antora \
$ podman run -v $PWD:/antora:Z --rm -it antora/antora \
  --clean \

will become, once pasted:

podman run -v $PWD:/antora:Z --rm -t antora/antora version && podman run -v $PWD:/antora:Z --rm -it antora/antora --clean antora-playbook.yml

Note that the output lines (if any) are also removed.

Thank you again @ferdnyc for your contribution, I’m sure this will be very helpful for quick docs writers!


Would it be better to join them with ;? There may be cases where a non-zero return code should not halt the execution of the remaining commands.