Archive of Our Own ^beta

Chapter Text

Hello Friends

(If you've written some variant of "test" in the comments you count as a friend.)

I first published this in 2015. It's a decade later, A03 supports some new HTML, and and we're all walking around reading fic on supercomputers that fit in a jean pocket.

Some Housekeeping notes: things are a little messy around here. The once-a-decade overhaul to get this into an up-to-date second edition is near completion. The three chapter that were here were broken up into smaller concepts and new chapters added for this introduction, how HTML nests in itself and other bad ideas, the details and summary tags, links, and images. There are still places where you'l find missing attribute information, or example sections that are "to be added," and it's still incomplete because AO3 now supports audio and video tags, so we'll need those too.

This entire work is formatted for desktop. It displays ok on a tablet in landscape mode, but there's a lot that won't work if you're reading it on your phone. Given what a pain it is to type HTML tags on a phone, I’m ok with this. It also is a very visual guide and I haven't tested it with Text-To-Speech (TTS) or any other screenreader. Tables in reports I have to review for work are bad enough, I don't want to listen to my own. So I'm ok with that too.

For those who've been here from the start, and everyone testing and commenting after the new chapters have gone out: Thanks for being on this ride with me.

Second Edition Table of Contents

1.    Introduction (and Housekeeping Notes)
2. In Line (Text) Formatting: Simple

   address b big cite code del em

   i ins kbd q s samp small

   strike strong sub sup tt u var

3. In Line (Text) Formatting: Advanced

   abbr acronym dfn

   rp rt ruby

   span

4. Section Formatting: Paragraphs and Spacing

   br center

   hr p

   pre

5. Section Formatting: Headings, Quotes, Divisions

   blockquote div

   h1 h2 h3

   h4 h5 h6

6. Section Formatting: Hide/Show Information

   details

   summary

7. Lists

   dd li

   dl ol

   dt ul

8. Tables

   caption col colgroup table

   tbody td tfoot

   th thead tr

9.    Bad Ideas (That You Can Do)
10. Links

    a

11. Media Embeds: Images

    img

    iframe

    object

12. Media Embeds: Audio

    audio

    source

    track

13. Media Embeds: Video

    video

    source

    track

14. Media Embeds: Iframe & Embed

    iframe

    embed

15. Figure & FigCaptions

    figure

    figcaption

"Plain Text With Limited HTML" on A03.

The archive allows users to enter "Plain Text With Limited HTML" into:

• Profiles
• Series Summaries
• Series Notes
• Works or Work Chapters
• Work Summaries
• Work Notes (beginning and end)
• Chapter Notes (beginning and end)
• Comments
• Bookmarks

And probably some other places I've forgotten. At times AO3 has, and will again, prohibit some of the 'allowed' HTML in the comments. This is usually limited to turning off links and images due to spambots.

Previously, No CSS skin had been added to this work. What you saw was the unmodifed default A03 formatting for each of these HTML tags. In this update the Public Work Skin Basic Formatting has been applied. This is mostly to allow for table outlines throughout the work (A03 defaults to no visible outlines on tables). Except for table outlines and where explicitly noted, this skin is not used. This work remains what-you-see-is-what-you-get (WYSIWIGwhiz-ee-wig) and is completely readable with the workskin turned off.

If you are using a work-skin you can use the classes defined in it for any "work" field: notes, chapters, or chapter notes. It will not effect non-"work" fields such as the summary or comments.

HTML 101

HTML stands for Hyper-Text Markup Language. Basically it's a way to format your work. This is accomplished through the use of tags - basically a formatting instruction inside of < > brackets. Almost all tags will have an opening tag like <tag> and a closing tag like </tag>. All of the text between those tags is formatted by the tag.

It really is that simple.

There are two main places tags can get applied: to create a section of text, or in-line to modify words within a section of text.

Sections

This includes things like paragraphs (added automatically by A03's HTML parser if you're too lazy to code them yourself), divisions, tables, lists, and headings. Basically wherever we're making a container to put text into. This could be a paragraph shaped container, a hide-the-spoilers (detail) shaped container, a list shaped container, etc. Most users of A03 will never use this functionality, but we're covering it all here.

In-Line Editing

Thisis what almost everybody is here for. This is how you modify the formatting of some or all of the words within a section. This includes visible formatting changes like making text larger or smaller, into superscripts subscripts, monospaced, italic, bold, or underlined. It also includes less visible changes like letting a Text-to-Speech (TTS) reader know what words to emphasize, or identifying quotes or citations within the text.

Going back to how tags work: a tag stays open until you close it. And you can put other tags inside of it, like a series of nesting dolls:

If you don't want to take my word for how HTML works, there's a nice HTML tutorial at w3schools that you could work through on at your own pace. It's way more interactive and more comprehensive than this guide, and includes a lot of features that are turned off within the archive.

HTML 102: Empty Tags

So I lied about tags needing to be closed. Most tags absolutely need to be closed, but there are there are a few tags that don't format text or other content, so they don't need to be closed. These are called empty tags or an empty element. The archive supports the following empty elements - they'll be explained more in their chapters. When using an empty tag you can type it as normal: <hr> - I use this format throughout the guide - but the archive's HTML sanatizer will clean it up to modern standards by adding a space and a closing slash so it looks like: <hr />. If you go to re-edit a work and see this, don't worry, it'll still work fine. You don't need to make any changes.

Archive of Our Own's HTML Sanitizer(s)

So if you mouse-over the  ?  above most fields, you can open an infomation window that reads:

Allowed HTML

a, abbr, acronym, address, [align], [alt], [axis], b, big, blockquote, br, caption, center, cite, [class], code, col, colgroup, dd, del, details, dfn, div, dl, dt, em, figcaption, figure, h1, h2, h3, h4, h5, h6, [height], hr, [href], i, img, ins, kbd, li, [name], ol, p, pre, q, rp, rt, ruby, s, samp, small, span, [src], strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, [title], tr, tt, u, ul, var, [width]

This is mostly true.

The reason we know it's only mostly true is that Archive of Our Own is that the amazing volunteer-maintained code that runs it is freely available on GitHib. If you've ever programmed anything it's pretty readable. The current HTML Sanitizer code specifically allows:

Copied from GitHub on 2025-03-09:

elements: %w[

a abbr acronym address b big blockquote br caption center cite code col colgroup details figcaption figure dd del dfn div dl dt em h1 h2 h3 h4 h5 h6 hr i img ins kbd li ol p pre q rp rt ruby s samp small span strike strong sub summary sup table tbody td tfoot th thead tr tt u ul var

],

attributes: {

all: %w[align title dir],
"a" => %w[href name],
"blockquote" => %w[cite],
"col" => %w[span width],
"colgroup" => %w[span width],
"details" => %w[open],
"hr" => %w[align width],
"img" => %w[align alt border height src width],
"ol" => %w[start type],
"q" => %w[cite],
"td" => %w[abbr axis colspan height rowspan width],
"th" => %w[abbr axis colspan height rowspan scope width],
"ul" => %w[type]

},

If you want to learn more about the sanitizer, AO3 News has a Tutorial: HTML Sanitizing and Parsing that goes over a lot of this.

Although the archive (in March 2025) does not host images, audio, or video, it does allow the HTML needed to embed these things. Depending on the tag/method used to embed audio or video, it will go through either:

• The embed sanitizer (embed, objet, iframe)
• The media sanitizer (audio, video)

These will allow more attributes, depending on the tag (and the tag's sanitizer) used.