Skip to content
Writing Systems Technical Resources

Style Guide

This is a guidance document for authors, primarily the Writing Systems Technology (WSTech) team.

Writing style

The writing style for site content should be appropriate to the type of content, so may not be consistent throughout the site. Some reference articles may need a more formal, neutral-observer, academic style, with no use of ‘you’ and limited or no contractions (e.g. shouldn’t). Guides and less formal articles may communicate more effectively through a more informal style, where guidance is given in a personal manner, such as ‘At this point you may want to consider…’.

In all cases avoid the personal pronoun ‘I’ except when quoting directly. ‘We’ can be used, but only to refer to the Writing Systems Technology (WSTech) team as a collective author (We recommend that…).

When providing guidance regarding best practice try to provide some indication of whether it is subjective opinion or objective fact. Recommendations should generally be in bold, and fall into four loose types:

  • Developers may choose to - There is no single good option, and developers should consider various alternatives.
  • We recommend that - There seems to be one option that is best for most developers, that we ourselves have chosen and that we suggest that others follow.
  • Ascender and descender values should - There is clearly a best option and to do otherwise would be asking for problems.
  • Production glyph names must or Font names need to - if you don’t do this then your font is unlikely to work properly.

Language, spelling, punctuation, and dates

Content should mainly be in English, however, that is not a rule, and content in other languages is welcome. If there is a need for multiple versions of a page in different languages we may wish to install extensions that make it easier to author and navigate between content languages.

English spelling may be American, International, or British to reflect the diversity and personal style of team members. It should, however, remain consistent throughout a page or pages of interrelated content. British text should use Oxford spelling, with the -ize ending for words such as organize, realize, and privatize, but with words ending in -yse retaining the s, as in analyse and catalyse etc.

Punctuation should follow general guidelines:

  • Quotations can use either single (British) or double (American) quotes as long as they are consistent throughout a page, although single quotes are slightly preferred. Place punctuation marks outside of quotation marks unless the punctuation is part of the quotation itself. This practice is sometimes referred to as ‘logical punctuation’. Source files can use either straight or ‘curly’ quotes—rendered pages will convert them to typographic ones.
  • Comma-separated lists should use the ‘Oxford comma’ to provide clarity, as in: The design process involves initiating, experimenting, forming, harmonizing, and adapting. This can be applied flexibly.
  • Ampersands should only be used when they are part of a name or title or heading, such as Scripts & Languages.
  • The copyright symbol © should be used rather than (c) except in quotations or examples.

Dates should generally be formatted as yyyy-mm-dd (e.g. 2025-02-27) to avoid confusion. Use specific dates where known. Avoid terms that assume the present time, such as ‘ten years ago’ or ‘currently’.

Capitalization

Page titles should use English title case, in which first, last, and any major words are capitalized, but not minor words (conjunctions, prepositions, articles).

All other headings should use sentence case, in which only the first word is capitalized except for names and proper nouns.

AI use

Although in some cases it may be difficult to avoid encountering AI-generated content when researching and authoring content for this site, it may only be used for reference purposes and never to directly prepare text or image content. All content must be authored and edited by one of the site’s authors. Use of AI should also reflect SIL’s AI Ethics Statement.

Referencing

(to be added later based on further discussion)

Figures & illustrations

Original or SIL-owned figures, illustrations, and images do not require captions or figure numbers if the in-text reference to it is close to the image and the reference is obvious. Figure numbering can be used if helpful, although it can make later page maintenance more difficult. Numbering should start at ‘1’ on each page and not be carried over to other pages, even if the content is related. There is no existing or planned system for automated figure numbering.

If the image is not original, the source of the image and by what permission it can be used must be included in a caption or in the text. Captions do not have any special handling but can be used - see Images. Captions can contain any kind of information, including links, and do not require use of figure numbering.

Filenames

Page filenames should be:

  • all lowercase
  • with no spaces or underscores
  • using real words (not abbreviations) separated by hyphens
  • that represents the page title (or a short version of it)

as in: font-licensing.md or style-guide.mdx.

Page metadata

Metadata is defined in the YAML header of each page. Here is a complete example including all optional fields. Note that formatting and indentation is very important, particularly for sidebar.

---
title: Page Title
subtitle: Page subtitle
description: General description
authors: Authors names
sidebar:
    order: 1234
    label: Alternate sidebar title
    hidden: true
lastUpdated: 2025-02-27
draft: true
---

Here are details, with required fields in bold.

  • title - required by system, should be unique, should use Title Case
  • subtitle - optional
  • description - required by us, but not normally shown to viewers
  • authors - optional, a single string of text that describes the author(s) and editor(s), normally listed in alphabetical order by last name
  • sidebar: order - required by us, use topic # from the WSTR Classification
  • sidebar: label - optional, replaces title in sidebar only, useful if page title is too long for sidebar
  • sidebar: hidden - optional, keeps page from being listed in sidebar
  • lastUpdated - required, use yyyy-mm-dd format, should be the date the content is current as of, not the date a minor typo was fixed. This will not be strictly enforced as there may be good reasons for a specific page to not include it.
  • draft - optional, hides page from production builds, not currently recommended

Markdown use

Page sources need to use the flavor of Markdown supported by Starlight as documented in Authoring Content in Markdown. Additional markdown reference material can be found at the Markdown Cheat Sheet.

The following examples are intended as a reference but also to test all the elements with the site CSS. If you use markdown elements that are not documented here please add them to this page. This enables us to adjust the CSS in the future and quickly see the impact it may have on page layout.

Text formatting

Text can be bold, italic, strikethrough, or inline code. Note that for clarity please use double asterisks for bold and single underscores for italic.

Text can be **bold**, _italic_, ~~strikethrough~~, or `inline code`. Note that for clarity please use double asterisks for bold and single underscores for italic.

Headings

Heading 1 is only used by the page title. Anchors are automatically generated for all level 2 <h2> and level 3 <h3> headings. The heading title can be added to the page URL with a hash, replacing spaces with hyphens, and making it all lowercase. A heading of ‘AI use’ would become #ai-use.

Heading 2 - main headings on a page

Heading 3

Heading 4

Heading 5
Heading 6
## Heading 2 - main headings on a page


### Heading 3


#### Heading 4


##### Heading 5


###### Heading 6

Lists

  • First item
  • Second item
    • Sub item
    • Another
  • Third item
- First item
- Second item
    - Sub item
    - Another
- Third item
  1. First item
  2. Second item
  3. Third item
1. First item
2. Second item
3. Third item

Tables

SyntaxDescription
HeaderTitle
ParagraphText
| Syntax | Description |
| ----------- | ----------- |
| Header | Title |
| Paragraph | Text |

It can also be slightly simplified, without the left and right pipes:

Unicode blockFont support
C0 Controls and Basic LatinU+0020..U+007E
C1 Controls and Latin-1 SupplementU+00A0..U+00FF
Unicode block | Font support
------------- | ------------
C0 Controls and Basic Latin|U+0020..U+007E
C1 Controls and Latin-1 Supplement|U+00A0..U+00FF

When text requires wrapping in cells, the relative width of columns can be somewhat adjusted by tweaking the --- | --- line under the header:

Unicode blockCharactersLong explanation
C0 Controls and Basic LatinU+0020..U+007EThis is a longer text to describe the basic Latin block
C1 Controls and Latin-1 SupplementU+00A0..U+00FF
Unicode block | Characters | Long explanation
------------- | ---- | -----------------------------
C0 Controls and Basic Latin|U+0020..U+007E|This is a longer text to describe the basic Latin block
C1 Controls and Latin-1 Supplement|U+00A0..U+00FF|

Table columns can also be aligned using :---: syntax.

Left-alignedCenteredRight-aligned
This is a longer text to describe the basic Latin blockC0 Controls and Basic LatinU+0020..U+007E
More left-aligned textC1 Controls and Latin-1 SupplementU+00A0..U+00FF
Left-aligned | Centered | Right-aligned
:------------- | :------------: | -------------:
This is a longer text to describe the basic Latin block|C0 Controls and Basic Latin|U+0020..U+007E
More left-aligned text|C1 Controls and Latin-1 Supplement|U+00A0..U+00FF

Images

Image location, filenames, and size

Images used on a page should be placed in an images folder in the same location as the page, typically within a main topic (collection). They should normally be .png or .jpg. Other formats may work but are untested.

Image filenames should follow the format pppp[-n]-shortname.png where

  • pppp is the topic page number (suggestion not an absolute requirement)
  • n is an optional counter if you have multiple images on a page
  • shortname can be whatever you want (it-can-even-have-multiple-hyphens) but should be all lowercase

There should be no spaces. Use hyphens, not underscores. The optional counter is not required and does not need to relate to any figure numbering.

If you want to reuse an image on multiple pages within the same topic, name it with the topic number of one page and then reference it on another.

If you want to reuse an image from another topic you can either reference it directly using a relative path or copy and rename the file into the current topic images folder (as long as it’s small).

Images can be any size, but those intended to fill the main content column should be at least 720 pixels wide, and any size above that can be used. Astro will adjust the size and optimize the image automatically. There is no need to manually optimize images for a particular size.

Image references

To place an image on a page use this format, and do not leave AltText blank:

![AltText](images/picname.png)

Here is an example of an image reference:

This is alt text
![This is alt text](images/9800-full-image.png)

You can reference images wider than 720 pixels wide and they will be scaled down:

This is alt text
![This is alt text](images/9800-scriptsworldno1040ortext.png)

You can also reference smaller images:

This is alt text
![This is alt text](images/9800-small-image.png)

Or an external image:

An illustration of planets and stars featuring the word “astro”
![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)

To add a caption to an image add the caption after the filename:

This is alt text
This will be the caption text
![This is alt text](images/9800-small-image.png "This will be the caption text")

Inline images are not supported.

Image references should not be broken over multiple lines. They may still work, however the Decap system does not support them.

Note that link formats are not yet firm and may change depending on what decisions are made regarding general referencing.

It is generally preferred that links use named references. Rather than use the basic [text](completefilereference) format in text it is better to use [text][refname], then define each [refname] on a separate line later in the document. Note use of brackets rather than parentheses!

The refname format should be reasonably consistent. Suggestions that will make it easier for us to create a more robust referencing system in the future:

  • All lowercase, like page filenames [glossary]
  • Use hyphens, not spaces to separate words, like page filenames [font-bakery]
  • For WSTR pages use the filename without extension [unicode-concepts]
  • For links to website where we will likely have a lot of references, consider prepending an indicator to the site. Examples:
    • [adobe-agl] (Adobe)
    • [fdbp-line-metrics] (FDBP)
    • [gf-spec] (Google Fonts)
    • [gh-issue] (Github)
    • [glyphs-vertical-metrics] (Glyphs)
    • [iso-open-font-format] (ISO)
    • [iws-c2] (chapters of Implementing Writing Systems on scripts.sil.org)
    • [ms-char-design] (Microsoft)
    • [omni-types-of-ws] (Omniglot)
    • [pysilfont-req-chars] (pysilfont)
    • [sil-orthography-dev] (SIL)
    • [ss-unicode] (ScriptSource)
    • [uni-surrogates] (Unicode)
    • [wiki-writing-system] (Wikipedia)
  • Academic-style references to books, papers, etc. should use the author’s last name and year of publication, such as [smith2023] or [cozens2019]. If there are multiple works by the same author in the same year, add a letter to differentiate them, such as [smith2023a] and [smith2023b]. This is consistent with some academic citation styles.
  • Reasonable exceptions to this are frequently used references such as: [otspec], [wsbp], and [wsig].

For most shorter pages the reference definitions should be at the end of the page, but for longer docs such as Writing Systems Best Practice the reference definitions could be clustered at the end of each section. They aren’t rendered on the page so their location can vary.

Use the hash plus heading (#ai-use) to link to another section on the same page (level 2 or 3).

For internal links use only explicit paths from the src/content/docs base directory without the .md extension, such as /topics/layout/justification. Do not use relative paths like ./filename or ../filename.

Use a full URL for external links.

Use the hash plus heading (`#ai-use`) to link to [another section on the same page][ai] (level 2 or 3).


For internal links use only explicit paths from the `src/content/docs` base directory without the `.md` extension, such as `/topics/layout/justification`. Do not use relative paths like `./filename` or `../filename`.


Use a full URL for [external links][otspec].


[ai]: #ai-use
[glossary]: /reference/glossary
[script-tavt]: /scrlang/script-tavt
[unicode-bidi-algorithm]: /topics/analysis/unicode-bidi-algorithm
[otspec]: https://www.microsoft.com/typography/otspec/

Blocks

Code blocks begin and end with three backticks ```. Syntax formatting including Expressive Code features are available - see Code blocks.

Blockquotes use a > at the start of each line.

> Blockquotes use a `>` at the start of each line.

Rules

Paragraph before horizontal rule - note blank line after

Paragraph after horizontal rule - note blank line before

Paragraph before horizontal rule - note blank line after


---


Paragraph after horizontal rule - note blank line before

Asides

:::note
This is an aside. Details and options can be found in the [Starlight docs][starlight-asides].
:::

Footnotes

Here is an example of a footnote1 that will appear at the very bottom2 of the page. Footnotes will automatically be numbered sequentially when rendered.

Here is an example of a footnote[^1] that will appear at the very bottom[^anytext] of the page. Footnotes will automatically be numbered sequentially when rendered.


[^1]: Here is an example of how the footnote text is indicated. This example reference is in the text.

Comments

To add a comment in the markdown source that will not be displayed on the page, make a fake reference definition called comment, instead of a link use #, and place your comment in (). The comment must be preceded by a blank line, and can only be a single line. This is useful for leaving notes to other authors or yourself, but it will not be rendered on the page. It will, however, remain in the public source.

There is a hidden comment in the lines after this.

There is a hidden comment in the lines after this.


[comment]: # (This is the hidden comment text)

MDX extensions

The following extensions to markdown support may be useful. To use them requires using the .mdx file format rather than .md. This is essentially a normal markdown file, and all the above markdown features can be used, however .mdx allows for additional components and capabilities.

To use these extensions:

  1. Rename the file to have an .mdx extension.

  2. Import the component you want to use by adding an import to the top of your file, just after the frontmatter. For example, this will import the Badge component:

    import { Badge } from '@astrojs/starlight/components';

  3. Add the special element (in this case, Badge) to your page wherever you would like it.

    <Badge text="Note" variant="note" />

Badges

See the Starlight docs - Badges for details. Here are some examples:

Note Success Tip Caution Danger New New and improved New, improved, and bigger Custom

Steps

See the Starlight docs - Steps (or the source for this mdx file) for details and examples.

Caption styling

(to be added)

Footnotes

  1. Here is an example of how the footnote text is indicated. This example reference is in the text. ↩

  2. Footnote references can also be text but will still get numbered correctly. The references can be placed at the bottom of the markdown page. ↩