SWWS Theme

Style reference and sample page

This is an abstract block. Since this document already provides a Summary section, this abstract doesn't summarize the contents again. It is here only to show that it is supported by this theme.

Summary

This is an Org document. It serves both as a reference of the standard HTML elements and custom user interface components styled by the SWWS theme (Software Workers Theme), and as a sample HTML page that uses the look and feel provided by the theme. To see the sample page, open this document in Emacs and use the keyboard shortcut C-c C-e h h. This will export the document as an HTML file which you can then open in your web browser.

This theme comes with two color schemes: light and dark. Your web browser will activate one or the other automatically based on your system or browser's visual theme preferences (see Light and dark modes).

Documents using this theme will adapt to different screen sizes and should work well enough for printing as well.

The Cascading Style Sheets (CSS) provided by this theme are all valid CSS according to the W3C CSS Validation Service (last checked on April 03, 2023).

Source document: index.org

Light and dark modes

The SWWS theme supports two color schemes: light and dark. Color scheme selection happens automatically. The dark color scheme is used by default. If the user's desktop or web browser is set to use a light theme, the light color scheme will be used instead.

The automatic selection of light or dark color schemes was tested successfully in the following web browsers and systems:

  • Epiphany 42.4 (aka GNOME Web) on Guix System with GNOME
  • GNU IceCat 102.8.0esr on Guix System with GNOME
  • Google Chrome 108.0.5359.79 on Android 12
  • Mozilla Firefox 105.0.1 (Flatpak) on Guix System with GNOME

Automatic color scheme selection is known to fail in the following web browsers:

  • Ungoogled Chromium 109.0.5414.119 on Guix System with GNOME

NOTE: Automatic selection of light or dark color scheme might not work as expected in browsers with fingerprinting protection activated.


Text-level elements

emphasis (em)
This is normal text, and this is emphasized text that should look different from the rest.
link (a)
mark
This is normal text, and the following is highlighted text, which is achieved by using the standard mark element directly.
strong, bold
This is normal text, and this is strong or bold text.

Blockquote

The following text is quoted.

Org is a highly flexible structured plain text file format, composed of a few simple, yet versatile, structures — constructed to be both simple enough for the novice and powerful enough for the expert.

— https://orgmode.org/

This text is back to normal.

Code blocks

Code blocks always use a dark background. The CSS for syntax highlighting is not provided by the SWWS theme, it is expected to be generated automatically, inline by the emacs-htmlize package when the document is exported. The colors of the code correspond to those of the active Emacs theme. For this reason, the Emacs theme used when exporting the document should provide enough contrast to look well on dark brackgrounds.

1: ;; Lambda expression example from Elisp Manual.
2: (lambda (x)
3:   "Return the hyperbolic cosine of X."
4:   (* 0.5 (+ (exp x) (exp (- x)))))

Details and summary

Goal [52%]: Allow exporting to EPUB format

As an author, I want to be able to export my document to EPUB so that I can publish it in digital stores targeting the X device.

Headings

This document already has examples of level 1 and level 2 headings. The following is an example of levels 3 and 4.

Level 3

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Level 4

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Images

The following is a responsive image (has the class responsive-image). Its size is adjusted automatically depending on the size of the screen.

Untitled illustration from "Cinderalla"

The image itself is an untitled illustration from "Cinderella" from the book Les Contes de Perrault, an edition of Charles Perrault's fairy tales (public domain illustration by Gustave Doré).

The following is a vector image in SVG format. It is made responsive in the same way as the previous image.

SVG image test image

Figures

The following is an image with caption added using Org format. The image is made responsive, centered, and framed using the classes: responsive-image, centered-block, and framed.

Illustration 1
Figure 1: Tonge, Mrs Olivia Frances (1858-1949) A watercolour drawing of geckos from Sketchbook 16 of the Tonge Collection (public domain image).

Since Org's captioning for images doesn't seem to allow rich text (links, for example), the following figure is an alternative using HTML elements directly (figure, image and figcaption).

Photo 1
Photo 1. The Convair Model 118 "ConvairCar" in flight. November 1947. Unknown author. ( public domain image from the San Diego Air & Space Museum).

Lists

Ordered list:

  1. Place the product in a pod.
  2. Cover with cold water.
  3. Put the pod over high heat.
  4. Bring water to a boil.
  5. Turn off the heat.

Unordered list:

  • Coriander
  • Spinach
  • Tomatoes
  • Onions

Definition list:

casa
house
árbol
tree
perro
dog

Notes (footnotes)

The following paragraph has little numbers that take to the footnotes:1

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.2

Preformatted text

The following is standard HTML pre element.

$ guix describe
Generation 69	Mar 01 2023 11:56:52	(current)
  guix ab6e434
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: ab6e434eaab270fdbb3403935ef177cfec542ea5

The following is preformatted text added with Org's example block.

$ guix describe
Generation 69	Mar 01 2023 11:56:52	(current)
  guix ab6e434
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: ab6e434eaab270fdbb3403935ef177cfec542ea5

See Code blocks for another kind of preformatted text.

Tables

The following is a table with heading cells.

Table 1: Some English nouns in Spanish
Noun Spanish
soap jabón
book libro
phone teléfono

The following is a table without heading cells.

Table 2: Japanese vocals
A I U E O

To make a table use all the horizontal space available, apply the full-width class to it:

Table 3: Time it took for Bus A and Bus B to cover their routes during last week.
  Monday Tuesday Wednesday Thursday Friday
Bus A 30 24 32 31 26
Bus B 21 25 31 27 28

Tables with many columns tend to overflow horizontally in narrow screens because Org mode's HTML exporter does not wrap tables in a container offering automatic scrolling for such cases. If a vertical layout would not make sense for the table, a workaround is to type the table manually in standard HTML and wrap it in a container div element that uses the autoscroll class. For example:

Contained table. Narrow the window to see that the table does not overflow horizontally. Instead, a horizontal scroll bar appears when there is not enough space horizontally.
Column A Column B Column C Column D Column E Column F Column G
Value A1 Value B1 Value C1 Value D1 Value E1 Value F1 Value G1
Value A2 Value B2 Value C2 Value D2 Value E2 Value F2 Value G2

Tags   neat

Take a look at the heading of this section. It has a tag named neat. That's an Org tag.

Timestamps

Org's inactive timestamps (see Org's dates and times), look as follows.

  • Date: [2023-04-01 sáb].
  • Date and local time: [2023-04-01 sáb 12:33].
  • Date and time range: [2023-04-01 sáb 14:00]–[2023-04-01 sáb 16:00].

TODO items

The following is a bogus project plan that shows the styling of Org's TODO items.

TODO [66%] Bogus project

The following tasks must be done to be able to complete the project.

DONE Task 1: Gather information

Collect some bogus information in a digital document and share it with the whole development team.

DONE Task 2: Design the product

Base on the information gathered in Task 1, design the product.

TODO Task 3: Prototype the product

Use the design from Task 2 build the first prototype of the product.

Video

Videos are similar to images and figures. The following video, for example, is responsive, centered, framed, and it is placed in a figure with caption.

Video 1. A car being controlled with a gamepad in a Godot Engine project.

Verses

The following is an example of an Org verse block showing the lyrics to a song titled My rough and rowdy ways, by Jimmie Rodgers (1929):

For years and years I've rambled
Drank my wines and gambled
But one day I thought I'd settle down

I met a perfect lady
She said she'd be my baby
We built a cottage in the old hometown

But somehow I can't forget my good old rambling days
The railroad trains are calling me always

I may be rough I may be wild I may be tough and ???
But I can't give up my good old rough and rowdy ways

Sometimes I meet a bounder
Who knew me when I was a rounder
He grabs my hand and says boy have a drink
We'd go down to the poolroom
Get in the gang and then soon
The daylight comes before I'd had a wink

Org classes

At the time of writing the SWWS theme, the following were the classes specified in Org's manual (sorted alphabetically):

 1: .WAITING
 2: ._HOME
 3: .code-highlighted
 4: .done
 5: .figure-number
 6: .footnum
 7: .footref
 8: .linenr
 9: .listing-number
10: .org-svg
11: .section-number-N
12: .subtitle
13: .table-number
14: .tag
15: .target
16: .timestamp
17: .timestamp-kwd
18: .timestamp-wrapper
19: .title
20: .todo
21: div.figure
22: div.footnotes
23: div.outline-N
24: div.outline-text-N
25: p.author
26: p.creator
27: p.date
28: p.footnote
29: p.verse
30: pre.example
31: pre.src

From all these classes, only the following were explicitly styled in the org.css file:

Class Example
.done Todo items
.figure-number Figures
.footnum Footnotes
.footref Footnotes
.linenr Code blocks
.listing-number None
.subtitle Subtitle of this document
.table-number Tables
.tag Tags
.timestamp Timestamps
.todo Todo items
p.verse Verses
pre.src Code blocks

The following are the classes whose styling was deemed unnecessary. They simply inherit their style from the elements they qualify:

Class Example
.org-svg Images
.timestamp-wrapper Timestamps
.title Title of this document
div.footnotes Footnotes
div.outline-N Any section in this document
div.outline-text-N Likewise
p.author Postamble
p.creator Postamble
p.date Postamble
pre.example Preformatted text

The following are classes for which it was not possible to determine from Org's documentation when they are exported to HTML:

1: .code-highlighted
2: .section-number-N
3: .target
4: .timestamp-kwd
5: div.figure
6: p.footnote

Finally, the following are examples of generated class names based on custom content, they are not actual Org classes:

1: .WAITING
2: ._HOME

Org mode bugs?

Custom preamble not exported some times

This document sets Org mode's org-html-preamble variable to a custom preamble (see the Custom preamble section in the source of this document). It seems this operation must be done at the end of the document, but this doesn't seem to be documented.

Setting the variable org-html-preamble anywhere else in the document might not work as expected if some particular content follows it. Examples of content that prevents the custom preamble from being exported include:

Headings level 4 to 6
The level refers to the resulting HTML heading level. A heading with three asterisks in Org is exported as a level 4 heading.
HTML export blocks
Any export block containing literal HTML.

Tables are not contained

Org mode's HTML exporter doesn't wrap tables in a container with autoscrolling. Tables with many columns overflow horizontally in narrow screens. See the Tables section for an example and a workaround.

Can't create a listing of figures (images)

It is possible to automatically insert a listing of tables (see the section List of Tables at the end of this document), but using the same mechanism for figures (captioned images) doesn't yield the same result (nothing happens).

Unable to export HTML if there is a link to an undefined URI fragment

I was trying to link to the automatically generated List of Tables at the end of this document, which is exported with an HTML id value of list-of-tables. But using the value #list-of-tables in a link created in Org format, prevents the document from exporting to HTML with the message:

Unable to resolve link: "list-of-tables"

List of Tables

  • Table 1: Some English nouns in Spanish
  • Table 2: Japanese vocals
  • Table 3: Time it took for Bus A and Bus B to cover their routes during last week.

Footnotes:

1

A curious thing with footnotes in Org is that it seems you have to use a section called * Footnotes at the end of the document for the footnotes to be rendered correctly in the exported document. Also, that section name seems to be reserved: if you use it anywhere else in the document, the section is not exported.

2

This paragraph comes from a placeholder text known as Lorem ipsum.

Author: Software Workers

Created: 2023-05-21 dom 14:41

Emacs 28.2 (Org mode 9.5.5)

Validate