Help:Page styles

From Wikisource
Jump to navigation Jump to search
Page styles
An explanation of the methods use to apply CSS to a scan-backed work,

A CSS "stylesheet" can be applied to a Index page, which will allow every Page: namespace page within it to share the same styling. This CSS is automatically included when pages are transcluded using the <page/> tag.

You do not need to use CSS for a work if you don't want to. It is provided to make life easier, not harder.

How to apply CSS[edit]

The CSS is read from the /styles.css subpage of the Index page. If this page does not exist, no styles will be applied by default by the ProofreadPage extension.

Note: this is different to the CSS field in the Index page, which only applies to the Page namespace and does not transclude.

You can redirect a /styles.css to another CSS page (for example if a set of volumes share the same styles) but the redirect page may need to have the "content model" changed to "wikitext" (from "sanitized-css"), which currently requires an admin.[1]

Where the CSS is applied[edit]

Index-specific CSS is currently applied automatically in the following places:

  • In the Page namespace of that index
  • On the Index page itself[2]
  • On the transcluding page when pages are transcluded using the <page/> tag.
    • Note: is is not applied if you directly transclude with {{Page:XXXX.djvu}} syntax, or with {{page}}. Either avoid these constructions and use the <page/> tag (recommended) or you must manually invoke with <templatestyles src="Index:Foo.djvu/styles.css"/>.

How to write CSS[edit]

The CSS is a subset of full CSS called "sanitized CSS" provided by the TemplateStyles extension. It is the same as normal CSS, but it has restrictions on certain properties:

  • Some "rarer" CSS properties are not supported yet
  • Data URLs are not allowed
  • Image URLs not from Commons (or Wikisource) are not allowed

The CSS will only apply to the page content (it will not affect the rest of the Wikisource UI).

Classes and IDs[edit]

You can target CSS with "classes" and "IDs". Classes can apply to any number of elements (and any element can have any number of classes). Any element can have an ID, but it can have only one, and it should be the only element on the page with that ID.

Classes are targetted by CSS rules with a dot prefix (.), and IDs with a hash (#)

The following spans have classes and IDs:

<span class="red bold">Classes: red and bold</span>
<span id="green" class="bold">ID: green, class: bold</span>
<span class="red">Class: red (and not bold)</span>

Paired with this CSS:

.red {
    color: red;
}
.bold {
    font-weight: bold;
}
#green {
    color: green;
}

The result is something like this:

Classes: red and bold ID: green, class: bold Class: red (and not bold)

Inheritance[edit]

You can target elements that are children of other elements with the "child" and "descendant" selectors:

  • Target direct children with parent_selector > child_selector
  • Target all descendants (any number of intervening "generations") with ancestor_selector descendant_selector

For example, if you have Wikicode that produces the following HTML:

<div class="parent">Parent content.
  <div>Child content.
    <span>Grand-child content
        <span>Great-grand-child content</span>
    </span>
  </div>
</div>

Then you can have CSS like this:

/* This will only put a border around the "Child content." box */
.parent > div {
    border: 1px solid blue;
}
/* This will put separate green outlines around each of grand-child and great-grand-child boxes
 * (but not "child", because that is a div, not a span */
.parent span {
    outline: 1px solid blue;
}

Cascading[edit]

The "C" in "CSS" means cascading. This means that the rules can override each other in a well-defined order. For each property, which rule is applied is worked out like this:

  • Styles set directly on an element have priority, otherwise,
  • More "specific" styles have priority
  • If two rule have the same "specificity", the one that occurs last has priority

"Specificity" has a certain defined meaning, but generally speaking it is a measure of how "precise" the selector is. For example in the following HTML and CSS:

HTML CSS
<div class="red">Parent
  <div class="green">Child</div>
</div>
<div class="green">Child</div>
.green {
    color: green;
}
.red > .green {
    color: red;
}

In this case, for the class="green" element inside the class="red" element, the more specific selector .red > .green "wins" over the less specific .green and the element gets the style color: red;.

What to use CSS for[edit]

CSS is ideal for applying things that would otherwise require very tedious, repetitive or verbose inline styles:

  • Sizes and spacings of chapter headings
  • Sizes of block-quotes and surrounding spacings
  • Formatting of lists (for example adjusting bullet points)

Due to the ability to use selectors like :nth-child, they are also excellent for reducing bloated inline styles in tables.

Be semantically useful[edit]

CSS is one half of the structure-style separation-of-concerns provided by HTML (structure) and CSS (style). To use it to its maximum effect, it should be used "semantically". That is to say, provide meaning to content and then use that meaning to apply styling.

For example, this is semantically empty:

<span style="font-variant:small-caps;">Duke Orsino<span>: If music be the food of love, play on,

whereas this gives meaning to the first words:

<span class="character">Duke Orsino<span>: If music be the food of love, play on,

And can be targeted, along with all other characters' names, with this CSS:

.character {
   font-variant: small-caps;
}

You should also not abuse Wikicode syntax just because it gives you a shorthand for a different HTML tag which you want to use to target with CSS. ; and : provide <dl><dt> and <dl><dd> elements, representing "description list" terms and descriptions, respectively[3]. Only use them where this makes semantic sense (for example, a glossary or dictionary).

If you have a list, * (unordered) or # (ordered) are usually the correct choices.

What not to use CSS for[edit]

You should not use Index-based CSS to provide:

  • Indentation of paragraphs, even if the original work had them (see Wikisource:Style guide#Indentation). Indentation of list items is usually acceptable, within reason.
  • Removal of spaces between normal paragraphs, even if the original work did not have them (see Wikisource:Style guide#Paragraph spacing)
  • Global changing of fonts (e.g. serif), justification, font size or line heights (even if the original work had small or dense print)

All these should be provided through Dynamic Layouts or user CSS.

Remember that not all users have full-capable CSS devices. For example, many e-readers can handle only a very tiny subset of CSS. You should not use CSS for any content that must be shown even if the reader doesn't support any CSS. For example, using CSS counters to number lists or :after selectors to add dots after list numbers will result in the wrong thing being shown to users without CSS. As a rough guide, if it can't be copy-and-pasted, users will not see it when CSS is not available.

Avoid bare classes[edit]

You should also avoid using bare CSS classes in Wikicode when a template would do. For example, say you have a work that has character names typeset in a certain way, say green italic small-caps. If you don't want to repeat the formatting for each occurrence, you should define a template {{MyWork character}} to apply this (perhaps using it's own TemplateStyles):

<templatestyles src="MyWork character/styles.css"/><!-- or inline CSS, or other templates -->
<span class="mywork_character">{{{1}}}</span>

And then use it as follows:

Avast, ye, {{MyWork character|Long John Silver}}!

The following bare CSS in the work's page content is bad form:

Avast, ye, <span class="mywork_character">Long John Silver</span>!

This is to say: the classes defined in CSS (including work-specific CSS) should nearly always be invoked via a template, not directly. It is much easier to reason about and maintain templates than HTML/CSS, even if the template itself constructs HTML/CSS.

CSS vs templates[edit]

Some things are suitable to be handled by work-specific CSS, and other things are more suitable for a template. Consider using a template if:

  • The desired output requires "structural" elements like HTML tags.
  • The desired output is useful in other works (i.e. it is not work-specific). You can redirect the CSS subpage, but this means you forfeit any dedicated styles for this work.
  • As above, the styling is work specific, but so is the application. In that case, a work-specific template is more appropriate. Per-work CSS is more suitable for applying work-specific styling to generic classes.

You can still target the output of templates with work-specific CSS (the template in question should set a class to allow this).

The following are some templates set classes that can be usefully targeted with CSS (others can be found in Category:Templates applying classes for page styles):

What if I want CSS for a single page[edit]

If you have CSS that applies only to a single page (for example, a table), you can still use TemplateStyles as normal:

<templatestyles src="Index:Some book.djvu/p321_styles.css" />

This must be applied in the body of the Page page for it to transclude. Remember that the CSS will apply to the whole context where this one Page is transcluded—it will not be limited to this page only. So, use an ID or class or limit the effects of your page rule. For example:

table {
  border: 1px solid black;
}

will affect all tables on the final destination page, but

#errata {
  border: 1px solid black;
}

applies only to the element with the ID errata.

Notes[edit]


Read more[edit]

Other CSS resources that you may find useful: