Can I use HTML on the Archive?
You can use HTML on Archive of Our Own (AO3) to format your text in many places. There's some HTML that AO3 automatically applies to any content you're posting.
This is done by the parser and sanitizer, which are programs built into the Archive to review code. The parser adds code where it's missing or attempts to clean up messy code. The sanitizer removes disallowed or dangerous code.
For example, the parser adds line breaks wherever there is a single return in your text, and paragraph breaks wherever there is a double return in your text.
The fields where you can use additional HTML markup to format your content include but are not limited to:
- works
- your user profile
- notes
- the profile information of a challenge or collection
- summaries
- comments
The full list of allowed tags is:
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, ruby, rt, rp, s, samp, small, span, [src], strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, [title], tr, tt, u, ul, var, [width]
If you attempt to use something not on this list, AO3 sanitizer will remove the markup from your content.
In works, you can use CSS in the form of a work skin. If you would like to learn how to use public skins for your work, refer to the Skins and Archive Interface FAQ. If you would like to learn how to create your own work skin, refer to Tutorial: Creating a Work Skin.
In non-work fields, you can only use the above allowable tags. Inline CSS isn't permitted in any fields.
I don't know anything about HTML. Can I format my text without it?
The Post New Work form on Archive of Our Own (AO3) has a Rich Text Editor, which includes a toolbar you can use to format your work text without using HTML markup.
By default, the New Work page will open the HTML Editor. You can switch to the Rich Text Editor by selecting the button which says "Rich Text" at the top right of the Work Text field. You can learn more about the Rich Text Editor in What is the Rich Text Editor?
The Rich Text Editor is only available for the body of a work. If you would like to format the text of your Notes, comments, user profile, or collection profile, you will need to use HTML markup.
I don't know anything about HTML. Where do I start?
HTML is the abbreviation for Hypertext Markup Language. It's what you use to format your content when posting on the internet. This includes visual styling like making text bold or italicized. It also includes functionality, like embedding images and adding links.
All HTML tags are contained within the less-than and greater-than symbols, < and >. Because a less-than symbol defines the beginning of HTML code, emoticons which contain the less-than symbol may break your content. If you would like to use one of these symbols in your content, you can use the HTML code, "<" for less-than and ">" for greater-than, instead.
Most, but not all, HTML tags have an opening and closing tag. The difference is the closing tag has a forward slash (/) immediately after the less-than symbol. The style or functionality defined by the tag will be applied to all the text between the opening and closing tags.
When using HTML markup in a work, your formatting will be applied when you toggle to the Rich Text Editor or when you preview the work. It's always a good idea to preview your work to ensure your HTML markup is working as intended. This way, you will have the opportunity to revise your HTML markup to get it right before posting.
These FAQs will walk you through using HTML on Archive of Our Own (AO3) for the following example scenarios:
- How do I make text bold or italicized using HTML markup?
- How do I make my text a heading using HTML markup?
- How do I post in a language that uses right-to-left script?
- How do I format bulleted or numbered lists using HTML markup?
- How do I add a link using HTML markup?
- How do I link a user to somewhere else on the page they are already on?
- How do I post images on the Archive?
If you'd like to learn more about HTML in general, there are many sites offering tutorials and explanations such as the w3schools.com HTML Tutorial.
How do I make text bold or italicized using HTML markup?
The tag for making certain text stronger than the rest, which renders as bold in most browsers, is <strong>. The tag for emphasis, which renders as italicized in most browsers, is <em>. These both require closing tags. They are a good place to start if you aren't familiar with HTML.
For example, you could put the following in your Notes:
Thanks for reading my story. I <em>love</em> this fandom and <strong>love love</strong> this pairing.
And it would be formatted as:
Figure 1: Formatted Notes section using the above code.
You can apply more than one type of formatting to the same text. The above example could be updated to have the following markup:
Thanks for reading my story. I <em>love</em> this fandom and <strong>love <em>love</em></strong> this pairing.
And your Notes would be formatted accordingly:
Figure 2: Formatted Notes section using the updated code.
When applying two types of formatting to the same text, the order of the closing tags should be the reverse of the opening tags. If you have more than two formatting tags, the opening and closing tags should be nested to follow the same logic: the next tag closed is always the one that has been most recently opened. In the above example where "love love" is entered, notice that the bold is opened first, then the italics. Since the italics tag was the last opened, it's closed first, followed by the bold closing tag.
If your closing tags are not in the same order as the opening tags, the AO3 HTML parser will rearrange your closing tags to be in the correct order.
If you put in an opening tag but not a closing tag, AO3 will automatically insert a closing tag. This closing tag will be inserted at the end of the form field where it was entered. In this example, the automatically added closing tag would be at the end of your Notes. This prevents your formatting from affecting everything on the page that is below your content, like the kudos, other comments, or the AO3 global footer. This mistake is typically easy to catch when previewing your work since the formatting will continue past where you wanted it to stop.
While this example specifically walks you through using bold and italics in the Notes, the same tags can be used in any content areas that allow HTML on the Archive to style text.
How do I make my text a heading using HTML markup?
There are six default heading styles on Archive of Our Own (AO3). The HTML tag for heading one, for example, is <h1>. Heading tags need both opening and closing tags. All text between the opening and closing tags display in the heading style defined in your markup.
Heading 1 is the largest, and they descend in size down to heading 6. The code for them is as follows:
<h1>This is heading 1</h1><h2>This is heading 2</h2><h3>This is heading 3</h3><h4>This is heading 4</h4><h5>This is heading 5</h5><h6>This is heading 6</h6>
If you put the above example code into the introduction field of a collection, you can generate an example of how each heading displays:
Figure 3: Example of six heading levels.
The example shows that heading 1 is always centered, heading 3 has a page-wide double underline under it, and heading 6 has a page-wide single underline under it. These styles are defined by AO3's site CSS. Most websites will have set styles for headings (although they may not always have all six), but the style and formatting of them will differ from website to website.
These heading styles are useful if you have a lot of information being displayed in a hierarchical way, like in the profile information for a collection. Screenreaders may allow users to jump from heading to heading to help those with accessibility needs find the information they are searching for. Using heading styles makes your text easier to scan for all users.
Here is a more representative example of how they would likely be used in collection info:
<h3>How awesome is this collection?</h3>The awesome-est!<h3>Give me the details</h3>You can skip this and go straight to the FAQs if you want.But you should probably read all this awesome text that I'm putting here.<h3>Eligibility</h3>You are eligible to participate in this collection if you sign up, create a fanwork in the necessary fandom, and post before the due date.
This would display in the finished collection information on the collection's profile as follows:
Figure 4: Example of information separated by h3 headings.
You can use this same markup to style headings in any other content areas that allow HTML on AO3.
How do I post in a language that uses right-to-left script?
You can post in a language that uses right-to-left script by using the "dir" attribute, which you can add through the Rich Text Editor or using HTML markup.
By default, the New Work page will open the HTML Editor. You can switch to the Rich Text Editor by selecting the "Rich Text" button at the top right of the Work Text field. Highlight the text you wish to make right-to-left, then choose the right-to-left button. In the text formatting options, the last option on the right on desktop (or furthest to the right on the lowest row on mobile), which shows the paragraph symbol with a left-pointing arrow, is the button that changes the direction of the text.
Figure 5: The right-to-left button in the Rich Text Editor.
If you'd prefer to apply the HTML yourself, or want to use a right-to-left language in a place that doesn't have the Rich Text Editor (such as a work summary, notes, or comments), you can add the "dir" attribute. The value of the "dir" attribute must be "rtl", which stands for "right-to-left".
The "dir" attribute can be applied to more than one element. For short text, it can be applied to the paragraph tag, "p". This markup would be as follows:
<p dir="rtl">בילי היקר,</p><p dir="rtl">מצורף מכתב אשר כתבתי עבורך. אני מקווה שאתה מתרשם <em>מאוד</em>.</p><p dir="rtl">בהערכה רבה,</p><p dir="rtl">אדלייד</p>
In this example, the "dir" attribute needs to be included in every paragraph tag. In a work or other long piece of text, this can be cumbersome to mark up individually, so the "dir" attribute can also be applied to a "div" element. "Div" stands for "division" and is a way to apply formatting to a larger section, which may consist of many smaller sections with their own markup.
An example of this is:
<div dir="rtl"><p>בילי היקר,</p><p>מצורף מכתב אשר כתבתי עבורך. אני מקווה שאתה מתרשם <em>מאוד</em>.</p><p>בהערכה רבה,</p><p>אדלייד</p></div>
Both examples will display as:
Figure 6: An example of Hebrew text displaying right to left.
Applying right-to-left markup to a "div" tag will only work if all the HTML markup between the <div> and </div> is correct. If any of the markup within the section is incorrect or if the parser applies any changes to the markup, it may break the right-to-left formatting. You should preview what you've posted when you're done to ensure your markup displays as intended.
How do I format bulleted or numbered lists using HTML markup?
The markup to define the start of a bulleted list is <ul>. In this markup "ul" stands for "unordered list".
The markup to define the start of a numbered list is <ol>. In this markup "ol" stands for "ordered list".
Lists require more than a single set of opening and closing tags. In addition to markup for the start of a list, each item on your list needs to be defined by its own HTML markup. The markup to define each bullet point or number in the list is <li>. In this markup "li" stands for "list item".
The first thing you need to do when creating a list is determine which type of list you're creating: bulleted or numbered. Then you need to include markup to define each item on the list. There are no additional elements required in these tags.
All of these opening tags require closing tags.
An example of where a list might be useful on Archive of Our Own (AO3) would be in a collection FAQ asking, "What are the steps to participate in this challenge?" An example of this markup is as follows:
<strong>What are the steps to participate in this exchange?</strong><ol><li>Nominate the characters you want to be included in the exchange</li><li>Sign up to participate in the exchange</li><li>Receive your assignment</li><li>Create a work</li><li>Post your work</li><li>All the works go live!</li></ol>
In the collection's profile FAQ this will display as:
Figure 7: An example of an ordered list.
This same markup can be used to create lists in any content areas that accept HTML markup on AO3.
How do I add a link using HTML markup?
The HTML tag for a link is <a href="[url goes here]">.
This tag contains an element and an attribute in its markup. An element is the initial piece of the markup which defines what type of code it is. Attributes define additional instructions for how the element works. In a link, "a" is the element, which defines that you are creating a link. The "href" is the attribute which defines where your link goes. In this markup, "a" stands for "anchor" and "href" stands for "hypertext reference".
An equals sign always follows the "href". After the equals sign, include the URL you are linking to in quotation marks. To link to a different site, the URL must start with "http" or "https". If you omit this, your link will not work.
After the closing quotation mark is the greater-than symbol, ending your opening link tag. All the text between the opening tag and the closing tag will display on the screen as a hyperlink. The closing tag just contains the element, "a", and not the "href".
This markup is the same for any place you want to include a link, whether it's to link to a prompt, a beta's account, your own website, or anything else.
One place people frequently include links is in their Notes when they thank and link to their beta. For example, you could put the following text in your Notes:
<a href="https://[beta's_tumblr_name].tumblr.com/">Thanks beta!</a>
This would display as:
Figure 8: Formatted Notes section displaying a link.
The full text of your link would be "Thanks beta!" Selecting this text would take you to the beta's Tumblr in the same window.
All links follow this same basic structure, no matter what they link to or which type of content on Archive of Our Own (AO3) they are in.
Using the same example, you could link to your beta's AO3 account instead of their Tumblr. If you were doing this, you could use a relative link. A relative link is when you are linking to a different page on the same website you are already on.
A relative link does not include the top-level domain name. This means it only includes the name of the page that comes after the ".com" (or in this case the ".org") in the URL.
If you were linking to your beta's AO3 account, the markup would be formatted as:
<a href="/users/[beta's_AO3_username]/">
There would be no change to the link's visual appearance in the work's Notes. The only change would be where the link goes when selected. When using HTML markup which has functionality, you should always test it when you're done. In this case, you would select the link to make sure it goes where you want it to go.
The attribute rel="nofollow" is added to all links on AO3 by the parser. If you make changes to your markup after preview, you may notice this. This discourages spammers from using AO3 to improve their search rankings, but will not impact the functionality of your link.
How do I link a user to somewhere else on the same page they are already on?
You can link a user to somewhere else on the page they're already on by using anchors. There are two parts to anchors:
- The anchor point, which is the destination
- The anchor link, which will take the user from where they are currently on the page to the anchor point.
Both the anchor point and anchor link use the same markup as links that go to new pages. If you are unfamiliar with the HTML markup for links, you can reference How do I add a link using HTML markup?
The HTML markup for setting the anchor point is:
<a name="anchor"></a>
When setting an anchor point, you define a "name" element in your tag. Your anchor name will not display to people accessing the page. If you have multiple anchor points on the page, each one must be unique.
The Archive of Our Own (AO3) already has some built-in anchors throughout the site. For example, the "Top" button at the bottom of a chapter or work brings you to the top of the page using the anchor "main". Make your anchor names specific to your usage so that they don't conflict with any already in use by AO3.
The anchor point markup requires a closing tag, with no text required between the opening and closing tags.
The HTML markup for the anchor link is:
<a href="#anchor">
The "href" element should contain your anchor name, preceded by a hashtag.
Anchors can be used in both works and non-work locations. In a work, you might use this to link to footnotes.
In the body of your work, the markup could be coded as:
The princess was wearing a sacque gown<a href="#sacquedefinition" name="sacquedefinitionback"><sup>1</sup></a> as she entered through the double-doors of the ballroom.
In your Notes, you would need the corresponding markup to set the anchor point:
<a name="sacquedefinition"></a>1. A sacque gown is a style of women's fashionable dress from the 1760s with box pleats in the back and wide panniers under the skirt portion, think Marie Antoinette. <a href="#sacquedefinitionback">Back</a>
In this example, the a tag in the work is both an anchor point and anchor link. A user can select the "1" annotation link in the work to access the footnote. They can then select the "Back" link in the footnote to return to where they were in the work.
In the body of the work it would be formatted as:
Figure 9: A footnote indicator displayed in a sentence.
The "1" displays as a superscript, smaller and above the rest of the text because it's wrapped in the sup tag. sup is a text styling tag that can be used on the AO3 following the same instructions as those for the bold and italics formatting.
In the Notes, it would be formatted as:
Figure 10: Formatted Notes section displaying a footnote.
In a non-works location, you might use anchors in an exchange challenge to link from a list of FAQ questions to their respective answers.
As with all HTML markup that adds functionality to a page, you should test the functionality when you're done to make sure it works as intended, and revise if necessary, before directing users to the page.
How do I post images on the Archive?
The HTML tag for images is <img src="[image url goes here]" />.
This tag contains an element and an attribute in its markup. An element is the initial piece of the markup which defines what type of code it is. Attributes define additional instructions for how the element works. In an image, the "img" is the element which defines that you are embedding an image. The "src" is the attribute which defines the location of the specific image embedded. In this markup, "img" stands for "image" and "src" stands for "source".
An equals sign always follows the "src". After the equals sign, include the image URL within quotation marks. Embedded images don't need separate closing tags, as they are opened and closed within a single tag.
This is the markup you would use to embed images in a content field like Notes, a work, or a collection profile. Note that Archive of Our Own (AO3) cannot host images, so you will need to first upload your image to an external hosting site, then use the link to embed the image on AO3. Some image hosting sites work better than others, while some don't work at all. You can find a list of sites that don't work, plus suggestions for how to evaluate image hosting sites at How do I post an image?
After you have uploaded the image, copy the image URL. You can then paste the URL into your markup.
There are some limited instances, such as your user profile pic or collection profile pic, which are uploaded directly to the Archive. In those instances, please follow the prompts in the appropriate form to upload your image or refer to the relevant FAQ for more help.
If you are creating a work based on an image, you may want to include that image in your Notes. An example of this is:
This fic is based on the image:<img src="https://preview.ibb.co/dnat2G/image1_2.jpg" />
This would display as:
Figure 11: Formatted Notes section using the above image code.
If you don't define the size of your image, it will display at full size. This may be larger than the browser window and could require the user to scroll horizontally and/or vertically to access the whole image. You can define the size of your image with the attributes "width" and "height". The default units for the image size is screen pixels.
If you set one of these attributes, your image will size down proportionally in both directions.
In the above example this would be defined as:
This fic is based on the image:<img src="https://preview.ibb.co/dnat2G/image1_2.jpg" width="200" />
Which would display as:
Figure 12: Formatted Notes section using the updated image code.
When setting image sizes remember that people will be accessing your work on a wide variety of screen sizes, from desktop computers to smartphones and sizes in between.
Another attribute you can include is alternative text. Alternative text, or alt text, doesn't necessarily display on the page. It's available to users who are unable to view the image for any reason, or who are using accessibility tools to access works on AO3. The attribute for alt text is "alt".
Adding a defined image size and alt text, the example would now be formatted as:
This fic is based on the image:<img src="https://preview.ibb.co/dnat2G/image1_2.jpg" width="200" alt="photo of an origami bow" />
In this instance, the visual display of the image within the work is exactly the same as it was without the additional attribute; however, the work is now accessible for more people.
In the body of works, you can also use the Rich Text Editor to insert an image. For help doing so, you can reference How do I post an image?
Where can I get more information if my question isn't answered here?
For more information on HTML and how it can be used on the Archive, refer to HTML on the Archive and Tutorial: Posting a Work on AO3. For more information on HTML in general, you can refer to the w3schools.com HTML Tutorial.
For information on other ways to format your work using skins, refer to Tutorial: Creating a Work Skin and the Skins and Archive Interface FAQ.
Some frequently asked questions about the Archive are answered in other sections of the Archive FAQ, and some common terminology is defined in our Glossary. Questions and answers about our Terms of Service can be found in the Terms of Service FAQ. You may also like to check out our Known Issues. If you need more help, please submit a Support request.
