Archive of Our Own

Chapter Text

Chapter 1: Introduction & Setup

You've seen it. A fic that has realistic social media posts. A work listing that looks like it was pulled from a museum archive. An interactive game, somehow, inside an AO3 work. You clicked the kudos button. You thought: how.

This is the tutorial that answers that.

This is a beginner-friendly guide to using HTML and CSS on AO3. No prior coding experience required. You just need a browser, an AO3 account, and a willingness to break things experimentally.

By the end of this work, you'll know enough to write formatted fic, style your own works, build your own AO3 site skin, and maybe make something that makes other people stop and think how.

Tutorial Table of Contents

This is an ongoing work. Chapters are added and updated. I have hyperlinked them below, so jump to whatever you need. Each chapter is written to stand alone, though Chapters 1, 2, and 3 are the recommended foundation before anything else.

Before We Start: What Is HTML?

HTML stands for HyperText Markup Language. That sounds technical. Here's what it actually means:

HTML is a way of labelling text so a browser knows how to display it. That's it. You're writing instructions that say: this part is a heading. This part is a paragraph. This part is bold.

You write those instructions using tags — little labels in angle brackets that wrap around your content. A tag has an opening and a closing, like a set of parentheses:

<p>This is a paragraph.</p>
 
<strong>This text will be bold.</strong>
 
<em>This text will be italicized.</em>

The closing tag has a forward slash before the tag name. Open a tag, write your content, close it. That's the whole model. Everything else is just more tags.

What Is CSS?

CSS stands for Cascading Style Sheets. Where HTML labels what things are, CSS controls how they look.

Want your headings to be teal? Your background to look like aged parchment? Your links to glow gold when hovered? That's CSS. It works by targeting an HTML element — a tag, a class, an ID — and applying visual properties to it.

h2 {
  color: #1B5E5E;
  font-size: 1.5em;
  letter-spacing: 0.1em;
}

Read that as: "Find every h2 heading. Make it teal. Make it 1.5 times the normal text size. Space the letters out slightly." CSS is extremely readable once you know the pattern, and the pattern is always the same: what to target, then what to do to it, written inside curly braces.

You don't need to memorize properties. You'll look them up. Everyone looks them up. The skill is knowing what to ask.

What Can You Do With HTML and CSS on AO3?

More than you'd expect. AO3 is one of the only major fan platforms that allows users to write raw HTML in their works and create CSS stylesheets that apply to the entire interface. All without any technical approval or account upgrade.

There are three distinct places HTML and CSS can live on AO3, and they work differently from each other. Here's a map of all of them.

1. Inside Your Fic Text (HTML Mode)

When you write or edit a work, AO3 gives you a text editor with a toolbar — bold, italic, link, and so on. What most people don't notice is the small HTML button at the far right of that toolbar. Clicking it switches the editor between rich text view and raw HTML view.

In HTML mode, you write the content of your chapter as literal HTML. The toolbar disappears and you have a plain text box. Everything you type is interpreted as markup: paragraphs, headings, custom layouts, collapsible boxes, decorative dividers, interactive elements. This is how every formatted fic in this series was made.

To write a chapter in HTML mode:

1. Go to Post New Work (or edit an existing one). You'll land on the standard work posting form.
2. Find the chapter text box. It has a small toolbar above it with formatting buttons.
3. Click the "HTML" button at the right end of that toolbar. The box switches to raw HTML mode. The toolbar fades out.
4. Write or paste your HTML directly into the box. If you're pasting from an external editor, make sure your source is clean. No Word formatting, no smart quotes from a word processor.
5. Click "Preview" before you submit. This is non-negotiable. The preview shows you exactly how AO3 will render your HTML, including any reformatting the editor has done. Fix anything that looks wrong before posting.

2. Workskins

A workskin is a CSS stylesheet that you create separately and then attach to a specific work. While HTML mode controls the content of your fic, a workskin controls the appearance. Workskins are what make drop caps appear, ornate borders draw themselves around the text area, and scene break dividers gain decorations.

You write the CSS once in your skin library, then select it from a dropdown when posting or editing any work. After that it applies automatically every time someone reads that work — including on mobile.

Creating a workskin:

1. Click your username in the top-right corner of AO3 to open the account menu. Select My Skins — or navigate to My Dashboard → Skins.
2. Click "Create New Skin." You'll land on a skin creation form.
3. Give it a name you'll recognize later — something like My Prose Workskin or the title of the work it's made for.
4. Set the skin type to "Work Skin." This is a dropdown near the top of the form. Make sure it's set to Work Skin, not Site Skin. They're stored in the same place but work completely differently.
5. Paste your CSS into the large CSS field. Don't add anything before or after the CSS itself.
6. Click "Submit." AO3 will validate the CSS. If there are errors, it'll flag them — usually a mismatched bracket or a disallowed property.

Attaching a workskin to a work:

1. Open the work posting or editing form for the work you want to style.
2. Scroll down to the "Associations" section. This is below the tags and relationships fields, usually near the bottom of the form.
3. Find the "Work Skin" dropdown. It will list all the workskins you've created. Select the one you want.
4. Submit or update the work. The skin will now apply to all chapters of that work.

3. Site Skins

A site skin is a CSS stylesheet that reskins your entire AO3 interface — the header, the navigation bar, the search results, the work listings, the comments, the footer, everything. It only affects how you see AO3. Other users still see the default. You can activate and deactivate it at any time.

Site skins are significantly more complex than workskins because you're targeting AO3's own HTML structure rather than a single container you control. But they're also more visually dramatic.

Creating a site skin:

1. Go to My Skins the same way as above: username → My Skins, or My Dashboard → Skins.
2. Click "Create New Skin."
3. Give it a name and set the skin type to "Site Skin." This is important as a site skin created as a workskin (or vice versa) will not behave correctly.
4. Paste your CSS into the CSS field and click "Submit."
5. Activate the skin. After submitting, you'll be taken to your skin's page. Click "Use" to activate it. The page will reload with your skin applied immediately.
6. To deactivate at any time, go back to My Skins, find the skin, and click "Stop Using." AO3 reverts to its default instantly.

4. HTML in Summaries, Notes, and Series Descriptions

Not every text field on AO3 behaves the same way. How much HTML you can use and whether your workskin affects it depends entirely on where the content appears on the page.

Beginning and end notes

Beginning and end notes are part of the work page. They render inside the same #workskin container as your chapter text, which means your workskin CSS applies to them, custom classes work, and the full AO3 tag list is available — <details>, <summary>, <table>, <div>, <span>, all of it. Anything you can do in your fic text, you can do in your notes. The one-line rule applies the same way: if you have nested or complex HTML, keep it on a single line to stop AO3's formatter from injecting <br> or <p> tags into your structure.

Work summaries

Summaries are inconsistent across AO3. On the full work page, a summary can pick up some of your workskin styling — especially if your CSS uses broad selectors like #workskin p, #workskin blockquote, or #workskin em. Basic HTML in the summary can therefore look noticeably styled there. In work listings, it's a different story: tags like <strong>, <em>, <br>, and links may still appear, but workskin-dependent styling is unreliable or absent. Keep summaries simple and don't rely on custom classes.

Series descriptions

Series descriptions behave more like summaries than notes. Basic HTML is allowed, but they have no access to your workskin. Assume limited formatting support and write accordingly.

What Can't You Do?

A few important limitations since it's better to know now than to spend an hour debugging something that was never going to work.

AO3's allowed tag list

AO3 doesn't allow all HTML tags. It maintains a specific allowlist, and anything outside it gets stripped silently. Most common text and layout tags are permitted. A few you might expect are not.

a, abbr, acronym, address, b, big, blockquote, br, caption,
center, cite, code, col, colgroup, dd, del, details, dfn, div,
dl, dt, em, figcaption, figure, 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

No JavaScript

AO3 strips <script> tags from user-posted content for security reasons. You cannot run JavaScript inside your works. Forms and checkboxes are also out — <input> and <label> aren't in AO3's allowed tag list at all.

What does work is the HTML <details> element, which toggles an [open] attribute on and off when a reader clicks it. Combined with CSS selectors that can detect that state, this is how all of the games in this series are built — the Tower of Hanoi, the Simon memory game, the Hangman games.

No external fonts in workskins (usually)

AO3's content security policy blocks most external font imports inside workskins. You're largely limited to system fonts and web-safe fonts, but this turns out to be fine. Georgia, Palatino, and their serif cousins are beautiful, widely available, and deeply appropriate for fic.

Some CSS properties are silently blocked in workskins

AO3's CSS validator drops a handful of modern layout and animation properties without warning. The main ones to know about upfront: display: flex and gap don't work. Use inline-block and margins instead. @keyframes and animation are blocked too. And id attributes are silently stripped from your HTML, which means CSS rules targeting #my-element won't find anything.

None of this is as limiting as it sounds once you know the workarounds, but it does mean "why isn't this working" is a question you'll ask, and the answer is sometimes simply "AO3 ate that property."

No layout control outside the text area

Workskins only affect the #workskin container — the box that holds your fic text. They can't move the sidebar, hide the header, or restructure the work page itself. That's site skin territory.

AO3 reformats your HTML

AO3's editor is enthusiastic about "helping." Blank lines between paragraphs get wrapped in <p> tags. Single line breaks become <br> tags. Multi-line HTML structures can get paragraph tags injected into them mid-element, breaking the structure entirely.

The main workaround is what I call the one-line rule: for any complex HTML structure put everything on a single unbroken line in your source. AO3 only injects <br> and <p> wrappers at line breaks, so a single line is never touched. It makes the source unreadable to human eyes, but it works. Write it formatted, then collapse it before pasting.

What You Need

Nothing you don't already have

1. An AO3 account. You need one to create skins and post works. If you don't have one yet, the invite queue is how you get in. You don't need any special account tier or permissions. Skins are available to all registered users.
2. A text editor. For short snippets, even the AO3 text box itself will do. For anything more complex, write your HTML and CSS externally and paste it in. Notepad on Windows and TextEdit on Mac (in plain text mode) work fine. A dedicated code editor like VS Code (free, Windows/Mac/Linux) or Notepad++ (free, Windows) is worth the five-minute download once you're writing more than a few lines. They color your tags so mismatched brackets become obvious at a glance. On mobile or tablet, Acode (Android) and Textastic (iOS) are solid lightweight options. If you'd rather not install anything at all, CodePen (codepen.io) lets you write HTML and CSS in a browser window and see the result live.
3. Reference material and practice grounds. You will look things up constantly. A few resources worth bookmarking: W3Schools (w3schools.com) is beginner-friendly, has working examples for every property, and has a Try It editor on every page so you can test changes instantly. MDN Web Docs (developer.mozilla.org) is more detailed and is the authoritative reference when you need to understand exactly what a property does. Neocities (neocities.org) is a free web hosting platform where you can build and publish test pages to see how your CSS looks in a real browser outside AO3's constraints. This is useful for diagnosing whether a bug is AO3-specific or just a mistake in your code. CSS-Tricks (css-tricks.com) has guides on specific techniques. Just search for whatever effect you're trying to achieve and there's usually a well-explained article.
4. A browser. Any modern browser. You'll be previewing constantly, so keep a tab open to your work's AO3 preview while you're editing. Chrome and Firefox both have excellent developer tools (right-click → Inspect) that let you look at AO3's underlying HTML structure, which becomes invaluable when writing site skins.
5. Somewhere to write drafts. It helps to keep a running document of your CSS as you build it, separate from the AO3 skin field, so you have a readable, commented copy you can come back to later. The AO3 skin editor has no undo history.
6. Patience with yourself. Things will look wrong before they look right. This is not a sign you're doing it wrong — it's how everyone does it. You'll break things, fix them, break different things, and learn more from each breakage than from any success. The first time a CSS rule does exactly what you intended, it will feel like magic. That feeling does not go away.

How This Tutorial Works

Each chapter covers one topic area. Chapters 2 and 3 are the foundation chapters: they establish the basic HTML and CSS vocabulary that everything else in this tutorial will use. That means they are a little denser than the chapters that follow. This is intentional. You are not expected to retain every detail immediately. Read for understanding first, then return to them as reference when later chapters start building specific effects from those tools. You can read in order or jump to whatever you need. I'm still learning new things and code on AO3 does break, so I will be updating the content periodically.

I write about what I've tested, verified, and made work, but HTML and CSS are broad, and AO3 has its own quirks that even somewhat experienced users run into unexpectedly. If something in this tutorial is wrong, outdated, or could be done better, please tell me. Comments are open, and I would rather be corrected than leave a mistake sitting in a tutorial that other people are learning from.

A Note on Copying

Everything in this tutorial is free to use, adapt, and share. If you find a technique here and want to use it in your own works or skins, go ahead. If you want to build on the CSS and post your own version, go ahead. Credit is appreciated but never required.