HTML markup tutorial

This tutorial teaches you the basics of how to do HTML markup for MIA. You don't need to know anything about doing HTML markup when you start. Also it should be noted that even though this tutorial covers a few topics beyond the basics, it's not necessary to go very deep; it's enough to get a basic understanding of the logic of how HTML markup works. For a complete beginner it's not necessary to go into the details of how exactly HTML operates. By all means, if you want, you can read through the "advanced" topics as well, and you can look for more information on various topics yourself elsewhere after you've been doing simple HTML markup for a while, but it's not necessary if you're happy to take the things that you read in this tutorial for granted and stick to simple HTML markup..

It's more or less the same with starting out with any new endeavour: first you just have to take the basics as they're handed to you, and only after you're at least somewhat comfortable using what you've been taught that you can start doing it more and more in your own way. And anyway, the idea is to keep the HTML on MIA relatively simple, so there's no pressure to learn or use any advanced tricks — you should simply aim to write clean and simple HTML.

What is HTML markup?

HTML markup is used to make the layout of a web page — it defines how text, images, tables and other elements appear to you in your browser. With a word processor such as Microsoft Word or LibreOffice, you write your text and then choose from the menus various kinds of options with which to change the appearance of your text: font type, font size, left and right margin, italics, bold etc. On the web the same outcome is reached by using HTML markup.

To illustrate the difference, select a simply formatted Word or LibreOffice document (.docx or .odt) from your own files, or write a few paragraphs of some text – no columns or tables, just plain text, maybe with some italics and bold text and some headings. Open it in Word and then 'Save As' a plain text document (.txt). Now, rename it to example.htm or something similar, the important thing is that the ending is now .htm. Then open the document in your browser (Firefox, Internet Explorer etc.).

You see that the document which looked fine in the word processor is just a string of words, no formatting, no paragraphs, no headings, just one long line. If you had italics or bold in the text, they're nowhere to be seen.

Open example.htm again in the word processor, and at the beginning of each paragraph insert <p>, at the end of each paragraph </p>, then pick a word and put <em> before the first character, and </em> after the last character of the word. Around the headings, put <h3> and </h3> in the same way. Then save the file (in txt format; if needed, rename the file again to example.htm).

Now open the file again in your browser. You should now see the document with paragraphing, and the word you surrounded with <em></em> is displayed in italics, and the heading(s) in bold and with a bigger font than the rest of the text.

Just like in a word processor, you can do all kinds of fancy-looking stuff besides these basics, but on MIA it's better to stick to relatively simple markup. You might be an HTML master, but in all likelihood you're not going to maintain an archive on MIA forever, and setting the bar too high for your follower could be problematic.

Let's take another simple example, where we've got a heading and two paragraphs. On MIA it would look like this:

This is a heading

This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph.

This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph.

If you look at the HTML source code (like your example.htm file) for it, it looks like this:

<h3>This is a heading</h3>

<p>This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph.</p>

<p>This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph. This is the second paragraph.</p>

See the bits highlighted in red? That's HTML code that tells the browser how to display each chunk of text. These bits of code are called tags. The way you use them to define a chunk of text is you surround the target text with an opening tag, a <p> for example (or <h3> for a level 3 heading) and a closing tag, a </p> (or </h3> for a level 3 heading). Most of the tags you're going to use on MIA will always have an opening and a closing tag, so that's a good rule to keep in mind (the few exceptions will be considered later).

This is the basic idea of making a plain text file into an HTML document that will look good on the web. A word processor works on a "what you see is what you get" basis, but HTML markup doesn't. If you're used to word processors, it might take a while to get used to the idea that almost everything you want to change in appearance requires you to change a tag, or add a new one.

Consider this example, where first there's the source text (in an .htm file viewed in a text editor or a word processor):

There's lots of spaces between the sentences, and more than enough lines between the paragraphs. But if you open it in your browser, it will look quite different:

This is the first paragraph. This is the first paragraph. This is the first paragraph.This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph. This is the first paragraph.

No matter how many times you press enter to put more lines between paragraphs, it will have no effect at all on how it looks on the browser, because an HTML document requires that instead of pressing enter to make another line break, you write the appropriate bit of HTML markup to perform a line break. With HTML markup, "what you see is what you get" is true only about the characters to be displayed. As the example above demonstrates, even multiple space bars between words will be cut down to just one.

The most common tags used on MIA

So the basic idea of how to formulate a plain text file in an HTML document is hopefully simple enough: surround it with the appropriate tags. There's lots of different tags for various purposes, but most of them you don't need to worry about if you just want to make straightforward HTML markup for MIA purposes. Here is a list with the most common tags that you'll be needing.

Paragraphs

Various kinds of paragraphs are formulated with the <p></p> tag (where "p" means "paragraph", of course.)

For paragraphs with first line indented: <p></p>

For paragraphs without first line indentation: <p class="fst"></p>

For indented paragraphs: <p class="indentb"></p>

For even more indented paragraphs: <p class="indentc"></p>

For quote paragraphs (with indentation): <p class="quoteb"></p>.

For quote paragraphs (with even more indentation): <p class="quotec"></p>.

These paragraph styles will serve you nicely for most purposes. As you can see, all the examples here use the <p> tag, but they still look different. This is achieved by putting an attribute inside the opening tag, for example <p class="fst"> instead of the plain <p> tag; class="fst" is the attribute in this case (to break it down further, class is the attribute, fst is the value). In this manner you can fine-tune the basic tags to your particular use. As a beginner though, you shouldn't worry about attribute fine-tuning at this point. They've been taken care of for you, and you'll be fine using just the ones given above (or elsewhere in this tutorial), and if you need more information, you can ask your mentor or the Steering Committee list.

Headings

Headings work the same way as paragraphs. Just surround the text you intend to use as a heading with the appropriate tags. Here are the headings that are used for texts on MIA:

<h3>Chapter title</h3>

<h4>Section title</h4>

<h5>Subsection 1 title</h5>

Emphasis

Here's the two main ways you can emphasize text:

For making text <em>italic</em>.

For making text <strong>bold</strong>.

Footnotes

Footnotes require markup that's somewhat more complex than just surrounding target text with tags. The following section is the hardest part of the basics tutorial, and it will probably take some time and trying out things before you can figure out the logic behind it.

In principle you could just put numbers in the text and their respective footnotes at the bottom (like in printed books where the footnotes are at the end of the book), but for the benefit of the users of the archive, footnotes in the text should be linked to the actual footnote text at the bottom (and vice versa). That way they can be accessed very easily, and the reader can return back to the main text just as easily.

Here's what footnote markup looks like, first in the source...

<p>Here is a sentence with a footnote.<a id="footnote1-top" href="#footnote1-bottom">[1]</a></p>

...and then in the browser:

Here is a sentence with a footnote.[1]

Let's analyze the source bit. The parts in red (<a></a>) are the opening and closing tags for anchor. The black text ([1]) in between the anchor tags is the text that will be the clickable link. The green and lime parts are the anchor's attributes. The green part states the unique identifier of this anchor, so that it can be referred to from somewhere else, in other words, so that you can make a clickable link in some other location, a link which will bring you to this very line. Each document must contain only one of each identifier, so two footnotes called footnote in the same document are not allowed; they must be called footnote1 and footnote2 or something similar. In the example, the footnote's identifier is footnote1-top.

The lime part determines the destination where you will be sent, when you click on the anchor (link) in question. The link in the example would take you to another anchor in the same document, one whose name is footnote1-bottom (see the image below).

Clicking on this link would take you to another anchor in the same document. This is because the href attribute's value (#footnote1-bottom) starts with a #, followed by the anchor's name. The # tells the browser to look for the anchor in the same document. If the # was left out, the browser would look for a file called footnote1-bottom in the same directory as the current document. If the anchor had the attribute href="example-directory/file1.htm", the browser would look for the file file1.htm in a directory that's in the same location as the current document. This allows you to delve into subdirectories. You can go the other way, too: href="../another-example-directory/file2.htm" would go up one directory from the location of the current document, look for a directory called another-example-directory, descend into it, and look for a file called file2.htm there.

Following the logic of this example, all footnote anchors in the main text that refer to a footnote at the end of the document would be marked-up as id="footnotex-top" (where x is the ordinal number for the footnote), because they're "on top" compared to the actual footnote text which is at the end of the document. Likewise, all the anchors at the bottom of the document are marked-up as id="footnotex-bottom, because they're "at the bottom".

Of course, you could give the footnotes some other name if you wanted something shorter. For example, the "top" footnotes could be called fnt1, fnt2 (for "footnote top 1", "footnote top 2") etc., and the ones at the bottom fnb1, fnb2 (for "footnote bottom 1" etc.)

So, to recap, for the purpose that's relevant here you can think of each footnote as a pair: The part in the main text refers to the bottom one, where the actual footnote text is, and the footnote text at the bottom refers to its counterpart in the main text, so that the archive user can click their way back and forth with ease.

One more thing. There's two kinds of footnotes: ones by the author of the text, and ones by the editor, translator, publisher or similar, which should not be confused with the author's footnotes. That's why it's a good idea to have to parallel series of footnotes running though the text, the author's footnotes denoted by [1*], [2*], [3*] etc., and all other footnotes, denoted by [1], [2], [3] etc. In other words, the asterisk is the distinguishing feature.

A concluding example with everything you need to know about footnotes follows.

<p>This is a sentence in the main text with a footnote by the author.<a id="footnote1-top-auth" href="#footnote1-bottom-auth"> [1*]</a>.</p>

<p>This is a sentence in the main text with a footnote by the
translator.<a id="footnote1-top" href="#footnote1-bottom"> [1]</a>.</p>

Author's footnotes

<p class="endnote"><a id="footnote1-bottom-auth" href="#footnote1-top-auth">This is what the author has to add to the subject.</a>

Translator's footnotes

<p class="endnote"><a id="footnote1-bottom" href="#footnote1-top">This is what the translator has to say about the subject, the translation etc.</a>

Bits and pieces

This section deals with some simple remaining guidelines for writing HTML for MIA.

Sometimes you need to break a line before it reaches the edge of the screen, if some author quotes poem, for example. The way to add a line break without making the next line into the first line of a new paragraph is with the <br /> tag. Note that this tag has only one part! No "closing tag" is needed (but remember the forward slash!). The following demonstrates the difference between <br /> and <p> line breaks:

<p class="fst">This is some words,</p>

<p class="fst">
This is some words,<br />
laid out like it was<br />
a poem.</p>

Technically speaking you can add extra line breaks anywhere with <br />, between paragraphs for example. However, it is recommended that instead of using <br /> for inserting empty lines between paragraphs, you use <p class="skip"> </p> instead.

Sometimes you need to keep two words together so that they won't end up on different lines on the screen, like in the case of "1 meter". If "1" and "meter" happen to be at the right hand edge of the screen, "meter" might end up on the next line, on the left-hand edge of the screen. To improve readability, you can insert a non-breaking space in between the words, so that they will always be on the same line on the screen:

"1 meter".

Let's now consider the reverse: some word needs to be broken across two (or more) lines. This doesn't happen so often in English as in some other languages that have long words, but if you have a particularly long word in the text, you might want to insert a "soft hyphen" into the word, so that it will be hyphenated at the right spot if the screen is very narrow (such as in a smartphone in portrait mode). You simply insert a  into where you want the word to break, if the word needed to be hyphenated:

"ultraimperialism".

Using  will produce a visible hyphen if the word is broken across two lines on the screen. Sometimes you don't want that, for example if your long phrase is a written out web address: a hyphen might be mistakenly thought to be a part of the address itself. In this case you might want to insert "word break opportunities" (<wbr>) into the address. <wbr> is another tag that has only one part:

https://www.marxists.org/<wbr>archive/<wbr>example-writer/<wbr>1912/<wbr>/our-present-tasks.htm

Sometimes the text you're working on is divided into separate sections. Depending on how strongly you want to separate two sections of the same text from each other, you can use a long line or a short one in between them. A long line could be in order if you've got two different articles in a periodical you're digitalising, and a short line (or something equivalent) is often used already in the original printed work itself when the author has finished talking about one theme and moves on to the next.

A long line, covering 94% of the screen width, is inserted with <hr class="end">. A short line, covering 42% of the screen width, is inserted with <hr class="section">. See this example box in the tutorial for what the lines look like.

If you need to insert fractional numbers, such as ¹⁄₂ and ⁵⁄₆, you need to know three tags: superscript, subscript and fraction slash. Superscript is made by surrounding the target word, number or expression with <sup></sup>. Subscript uses <sub></sub>:

This is some text.^{<sup>This is some superscript</sup>}. Fraction ⁵⁄₆ is written like this: ^<sup>5</sup>&frasl;_<sub>6</sub>.

Here's how you might need super- or subscript in practice, besides fractions: another way to write 10,000 is 10⁴, and the chemical formula for water is H₂O.

The fraction slash (&frasl;) is a special character, known as an HTML symbol entity, and you need to know the code for it. There's loads of characters and symbols available as HTML symbol entities that are not easily available, or not at all available, on your keyboard. In this case, you write &frasl; into your .htm file to insert a fraction slash in the document viewed on the browser. HTML symbol entities always begin with an & (ampersand) and end in a semicolon ;. A list of available HTML code characters is available here.

Some examples of HTML symbol entities follow.

← = ← (left arrow)
→ = → (right arrow)
< = < (less-than)
> = > (greater-than)
© = © (copyright symbol)
& = & (ampersand)
&permil; = ‰ (per mille)
&starf; = ★ (star)

Some characters are central to the HTML code, and you cannot write them "literally" into a text. For example, if you want to write "Marx & Engels", you cannot write the ampersand "literally", as a "&", in the text, because that will be interpreted as the start of an HTML entity (which always begin with an ampersand); you have to write the ampersand as an HTML entity instead of the "literal" character. So if you want that the page shows "Marx & Engels" in the browser, you must write it "Marx & Engels" in the HTML file you're editing.

Other similarly central characters are < (less-than) and > (greater-than), which open and close the HTML tags (like with <p>, for example). That's why you cannot write a "literal" 'less than' (<). If you need to write, "5 < 10" (five is less than ten), you must write it with its HTML entity: "5 < 10".

Working with HTML on your computer

Word processor or text editor?

One choice you have to make when you start is whether you want to work in a word processor or in a text editor. The advantage of a word processor is that it's probably familiar to most people who know how to use a computer. You can save your work in plain text and rename the file so that it has the .htm ending. To save in plain text in LibreOffice, for example, you choose 'Save As..' from the File menu, then click on the 'All formats' box, scroll down and select 'Text (.txt)'. Give your file a name and click 'Save'.

Word processors can save in htm format as well, so you might ask why you shouldn't do just that. The problem is that a word processor will write the HTML for you, and in doing that it will most probably try to make the resulting htm file appear in the browser as much as possible like what you see in the word processor. This won't work for MIA. Apart from aiming for a uniform look across the archive (which is why you should follow the HTML styles this tutorial talks about), MIA also aims for HTML that is a lot simpler and easier to read than what a word processor produces; typically the HTML produced by a word processor is far less "human-readable" and contains much more unnecessary information than clean, hand-written HTML.

If you stick to saving in plain text and renaming the file to something with an .htm ending, you'll probably do fine. Just don't feel tempted to get the word processor's "help" in writing the HTML!

Another option is to use a text editor, which will not offer to save in any particular format; instead you're always in "plain text mode". In addition, text editors that are geared towards programmers (and writing HTML markup is close enough to programming to count here) and offer functions (such as snippets) that are better suited for writing lots of repetitive text (such as HTML markup). There's an introduction to a free text editor called gedit available elsewhere on the MIA, have a look at it if you think that might suit your style of working.

It's up to you to decide whether to use a word processor or a text editor for your MIA work. Just remember that word processor documents (.docx, .odt etc.) should not be uploaded on MIA, and that you should always write your own HTML and save in plain text.

Copy the directory structure

Most likely you're doing HTML markup on your own computer at home, so it makes sense to copy of the relevant parts of directory structure of the MIA server to your computer. That way you can verify immediately whether your markup appears in the browser as you intend it to, and that all the (relative) links you have made are working.

Let's say you're working on the selected writings of Writer Example (in the English language archive). You'd have the kind of directory structure on your computer as can be seen from the image below.

The parent directory my-mia-work contains the directories for:

archive/example-writer, with directories for each year for which there are works from the author, with optional subdirectories for month, if the author in question has lots of materials available.
archive/template, containing ready-made templates which you can use with the skills you learn in this tutorial, with some of the more complex stuff taken care of for you. This directory is not part of the MIA archive structure, it is here just for convenience. Don't upload it to the MIA server.
css (for style sheets; you need to download these separately).
glossary/people/pics/e for images of authors whose last name begins with an 'e'.
whats-new/whats-new/whatsnew-template.htm (you need to download this separately).

You can download the example directory listing and its contents as a zip package for the English language archive or for other languages, extract it in some convenient location on your computer and see what it contains (the packages for English and others languages have slight differences in the directory structure, hence the different packages). You can open the archive/example-writer/index.htm file in your text editor and compare how the source HTML looks like when you open the file in your browser. Maybe make some changes based on what you've learned in this tutorial, maybe try some markup that's in the files but has not been talked about here etc. After making changes, save the file and refresh the browser page. Did something change, was it how you intended? And so on.

If you're working only with new authors that are not on MIA yet, you'll just create a directory for them in the directory tree on your computer, and then upload the files to the server when they're completed and tested. However, you might also need to work with files that are already on the server, if you're helping to maintain some bigger archive for example, and correct texts that you didn't proofread or or do the markup for yourself. In that case it makes sense to copy the relevant directories along with their contents from the server to your own computer.

If the file you're editing is a one-off case, then it makes sense to always copy the newest version from the server to your computer. Even though you might have edited the same file in the past and already have a copy of it on your computer, others may have edited it in the meanwhile, and you don't want to undo their work by uploading an older version of the file.

But if you've taken on the responsibility to administer the archive of some writer, and everyone knows that you're the administrator for that writer, then most of the time that means you're the only person editing the files in that archive. If someone spots a mistake, they come to you first. In that case it's more convenient to download the whole archive for that writer on your computer, where you know that you now have the most recent versions of the files, and it's going to stay that way, as you're the only person editing them. So in a case like this it's not necessary to download the file from the server every time.

Check your HTML for errors

It is guaranteed that you will make mistakes even long after you've mastered the basics. You forget to close a tag or you write some garbled nonsense because who knows what you were thinking. Browsers can be very forgiving and will try to guess what you meant with each incomplete tag or attribute. However, you should not rely on this, and you should routinely check your HTML for errors with the W3C Consortium's Markup Validator Service. You can check you page(s) either before or after uploading them of the MIA server (choose either 'Validate by File Upload' or 'Validate by URI'). The service will point out every single mistake you made and the line you can find it on. Often you might get dozens or even hundreds of errors, which turn out to be a cascading error because of one unclosed tag early on in the document. So don't be discouraged. Find the first error the validator service lists and start from there. Using the validator service is also a great way to learn how to write proper HTML.

A further way to control the quality of your HTML is checking the MIA bad references page every time after uploading something new on the server. This is not really an option, you really should do it.

How to use the templates

After poking around a bit, you can delete the stuff you don't need (= the directory example-writer and all its subdirectories with their contents), create a directory for the author you're going to work on, with subdirectories for each year etc., and use the templates in the zip package to get you started.

There's two templates, one for a page listing the author's works (for the time you start working on a new author and need to make a "home page" for them) and perhaps some information on the author ("author page template"), and one for the author's works ("work template"). Copy the template into your working directory, change the relevant bibliographical and MIA volunteer information to match what you're working on and save it under its actual name in the proper directory in the directory structure on your computer. (You might have to create the directory or directories as well.)

The author "home page" file is always called index.htm, and the work page name depends on what kind of work it is. The naming conventions for the files of the latter kind is available here.

Let's take a closer look at work-template.htm, or more precisely, the head of that file:

<!DOCTYPE html>
<html lang="en">
<head>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<meta content="WRITER'S NAME" name="Author" />
<meta content="All" name="Robots" />
<title>WRITER'S NAME: TITLE OF WORK</title>

</head>

Most of the information in the head you don't need to worry about, it will almost always be the same. There's only three bits that you need to change from work to work: "Writer's name" and "Writer's name: Title of Work" are hopefully easy to understand. The third one, namely the relative path to the works.css file, can be a more complicated issue. The number of ../ entries before css/works.css depends on your file's relative location in the directory hierarchy to the works.css file. This is likely to be an issue that takes some practice to get used to. That's why it has it's own section below (Using links in documents).

Let's take a look at the rest of the "top part" of work-template.htm.

<h2>WRITER'S NAME</h2>
<h1>TITLE OF WORK</h1>
<h3>1912</h3>
<hr />
<p class="information">
<span class="info">Written:</span> November–December 1911<br />
<span class="info">Published:</span> February 1912<br />
<span class="info">Translation:</span> T. T. (from Esperanto)<br />
<span class="info">Source:</span> <em>TITLE OF WORK</em>, Workers' Publishing Cooperative, 2nd edition, Paris 1912<br />
<span class="info">Digitalisation:</span> N. N.<br />
<span class="info">Proof-reading:</span> N. N.<br />
<span class="info">HTML:</span> N. N.<br />
</p>
<hr />

The changes you need to make in this section of the file are hopefully clear. You just need to fill in the bibliographical data on the text you're working on, to the extent that the information is available in the book, article etc. The lines that are not applicable can be deleted; for example, a text that is not a translation doesn't need a line about translation. A more detailed guide on the information going here can be found on this page.

Finally, the text in blue in the box above is a comment. You can make your own comments by starting a line with . These markers and everything in between will be a comment, and will not be visible in the normal browser view. You can also "comment out" parts of your text or code this way if you want to hide it temporarily, try out something etc.

You should paste the text you're working on under the comment text above, and you should use the skills you learn during this tutorial to change the appearance of the text. After the text, there's still one section that needs to be looked at.

<p class="skip"> </p>
<hr />
<p class="footer">
<a href="../index.htm">Writer Example Archive</a><br />
<a href="../../index.htm">Marxists Internet Archive</a></p>
</body>
</html>

There's three bits here to consider. The easiest is the name of the link to the author's archive main page. The two other bits are the relative locations of the mentioned files in the directory structure to the file that you're working on currently. Like above, you should refer to the section below on this question.

That's it for work-template.htm. Basically, copy your text in between these two sections, change the relevant information, and figure out the proper relative paths. The best way in the beginning is to just try some relative path, save the file, open the page in your browser and see if the link takes you where you want to go, while referring to the section on links below. This test method is one of the advantages of having the complete directory structure for the author on your own computer.

What's New? report template

In addition to the text templates, the zip includes also the following file: my-mia-work/whats-new/whats-new/whatsnew-template.htm. When you finish a text you're working on, you should fill in the template's required fields (i.e. replace the example entries) — the date you uploaded the work, the name of the archive, other information for the work in question, and the name(s) of whoever took part in preparing the text for publication on MIA. You can also check out MIA's What's New? page for actual examples of entries to the page.

After inserting the relevant information in the template, open the file in your browser and click the links to test that the relative links actually point to the intended files, then send the file as an email attachment to David Walters every time you upload something new into the archive (you can also finish a number of works before sending in a report, rather than sending a separate report for each work). David will add it to our What's New? page. As of December 2018, MIA's What's New? newsletter has almost 30,000 subscribers and it's an important record of how the archive has grown over the years, so be sure to send David the information!

Adapting your page for mobile devices

If you use one of the css stylesheets recommended above, you'll see that each includes a line @import url("works.css"); at the top of the file. This means that a block of code which adapts your layout for small screens which is located near the end of works.css is included. This code adjusts font sizes and margins so as to be appropriate for small screens.

In addition, you should include this line in the header of your HTML page: <meta name="viewport" content="width=device-width, initial-scale=1"/>. This will adjust the layout to fit the size of the client's screen.

If you use the templates suggested above, these measures have already been implemented and no further action is required.

Links to the zips, templates and CSS files

Here's the links to the template zips for quick reference so that you don't have to comb the text for them.

Here are the links to the three CSS files you'll need. Right-click on the links, select 'Save Link As' and save them all in my-mia-work/css/ after decompressing the zips on your computer.

Further topics

If you're a beginner, you should first wrap your head around the stuff in the previous sections and take some time to put what you've learning into practice by preparing materials for uploading on MIA. Once you're comfortable doing that (and if your mentor has accepted your HTML markup quality), you can proceed further. However, you can do most work for MIA with just what you've learned above.

Using links in documents

In a previous section you learned about anchors (links), and you also heard about going back and forth in the directory structure. Now that we've opened up the zip package and had a look at its contents, it's time to take up one more complex topic: the kind of links you should put into documents published on MIA. While in principle linking to external websites is fine, mostly there's no need to. However, all links that are made to documents on MIA should be relative, not absolute.

An absolute link to a document on MIA would look like this: https://www.marxists.org/archive/example-writer/1912/our-present-tasks.htm. This should never be used. Instead you should use relative links, the exact form of which depends on where the document with the link is in the directory structure.

If your document is in the directory my-mia-work/archive/example-writer/, and you want to refer to the file some-file.htm in my-mia-work/archive/example-writer/1918/01/, then your relative link looks like this:

The directory 1918 is in the same directory as your current document, so it's kind of intuitive to understand that this is the way it's done. However, what if you need to go back a directory level or two?

Let's say your document is in the directory my-mia-work/archive/example-writer/1918/01/ and you need to refer to the works.css file that is in the directory my-mia-work/css/. This is important, because at the start of every htm file you prepare for publication, you must make sure that the document finds the css file which contains the styles used in your document. Depending on where your document is located in the directory structure, the relative address of the css file changes, and you must take this change into account in your document.

So you'd need to go back four directory levels, then descend into the directory css and find the file works.css file there. Here's how it's done:

<a href="../../../../css/works.css">This link refers to works.css</a>

In other words, while there is no "special" way to go down a directory level (just write the name of the subdirectory), the way to go upwards a directory level is ../ — i.e. two dots and a forward slash.

Let's try another way to figure this out in practice. Open the directorymy-mia-work/archive/example-writer/1918/01/ in your computer's file manager. Now, start going back directory levels in the file manager. Count how many levels you need to go up before you find the directory my-mia-work/css/. It's four. That's how many ../ entries you need to add to the relative path in a file in my-mia-work/archive/example-writer/1918/01/ that needs to refer to the file my-mia-work/css/works.css.

Tables

If you do lots of markup, eventually you'll come across works that have tables — and lots of them. After this section you should be able to make relatively complex tables.

Here's an example of a table source code...

<table class="border">
        <tr>
                <td class="border">First row, first cell</td>
                <td class="border">First row, second cell</td>
                <td class="border">First row, third cell</td>
        </tr>
        <tr>
                <td class="border">Second row, first cell</td>
                <td class="border">Second row, second cell</td>
                <td class="border">Second row, third cell</td>
        </tr>
        <tr>
                <td class="border">Third row, first cell</td>
                <td class="border">Third row, second cell</td>
                <td class="border">Third row, third cell</td>
        </tr>
</table>

...and here's how it looks like in the browser:

First row, first cell	First row, second cell	First row, third cell
Second row, first cell	Second row, second cell	Second row, third cell
Third row, first cell	Third row, second cell	Third row, third cell

You start a table by writing <table>. Next, you declare a new row: <tr> (tr = table row). Under the tr tag you put as many td tags (td = table data) as there are columns on that row. The example table above has three columns per row, so there's three <td></td> pairs nested within one <tr></tr> pair. Hopefully this makes sense.

In the source code example above, the table data is laid out in a particular fashion to emphasize the structure of the table: from the layout it's easy to see which data belongs to which row. However, this is only for the source file. How the data is laid out in the source file has no effect on how it's displayed in the browser. So the following table could be written in the source file in the following way, and it would look the same as the example above, because the layout in the source file doesn't matter, only the tags and their order do:

<table class="border">
    <tr><td class="border">First row, first cell</td><td class="border">First row, second cell</td><td class="border">First row, third cell</td></tr>
    <tr><td class="border">Second row, first cell</td><td class="border">Second row, second cell</td><td class="border">Second row, third cell</td></tr>
    <tr><td class="border">Third row, first cell</td><td class="border">Third row, second cell</td><td class="border">Third row, third cell</td></tr>
</table>

In other words, instead of being on three separate rows, the three <td></td> pairs are one the same (source file) row, one directly after the other: <td>data</td><td>data</td><td>data</td>. Even the row tags are on the same line.

However, you should always aim at writing clear and "human-readable" HTML markup, and not write everything in one line just because it has no effect how it appears in the browser. Most probably you won't be looking after the pages you've made yourself forever, so others will need to be able to read what you've written. So it's a good idea to make their work easier!

The example table is with borders around each cell. This is good for tables with lots of rows and columns, especially ones where cells span multiple rows and/or columns. Consider the table at this link. It would be a lot more difficult to read if there was no borders around the cells, as it would be unclear just which columns the headings should refer to. But simple tables (like this one) do fine without borders. For a table without borders, just leave out the class="border" everywhere in the table:

<table>
        <tr>
                <td>First row, first cell</td>
                <td>First row, second cell</td>
                <td>First row, third cell</td>
        </tr>
        <tr>
                <td>Second row, first cell</td>
                <td>Second row, second cell</td>
                <td>Second row, third cell</td>
        </tr>
        <tr>
                <td>Third row, first cell</td>
                <td>Third row, second cell</td>
                <td>Third row, third cell</td>
        </tr>
</table>

...and it will look like this:

First row, first cell	First row, second cell	First row, third cell
Second row, first cell	Second row, second cell	Second row, third cell
Third row, first cell	Third row, second cell	Third row, third cell

Sometimes you need a table to have a certain width, so that the data in the cells is not too crammed together, for example. This can be done by adding the inline style style="width:640px" inside the <table> tag: <table class="border" style="width:640px">, where 640 can be some other number of pixels that the table should be wide. How wide the table must be has to be tried out in practice. Try different widths, check the outcome in your browser and decide which looks the most legible.

You can add the same width attribute inside a <td> tag as well, if some particular cell needs to be of a certain width for some reason. It's also possible to set the table width absolutely in pixels (absolute width in pixels makes the most sense from the point of view of legibility) first, and then set the width of the columns (one or all of them, it's your choice) in percent: style="width:20%", for example. If the table width is set absolutely (let's say to 640px), this means the 20% column width will in practice be absolute as well (20% of 640px is always 128px). The reason why setting column width (when you're still trying out stuff) in percent makes sense is that if you need to change the table absolute width, then you don't need to change individual column widths, as they will adjust automatically to be 20% (or whatever) from the new absolute table width.

Another useful style="x" trick is to change the text alignment within a cell. The default is to align the contents of each cell to the left, but often the table looks better if some cell content is aligned to center. This can be effected by adding style="text-align:center" into the opening <td> tag of those cells that you want aligned center:

<table class="border" style="width:320px">
        <tr>
                 <td class="border">Left</td>
                 <td class="border" style="text-align:center">Center</td>
                 <td class="border" style="text-align:center">Center</td>
         </tr>
         <tr>
                 <td class="border">Left</td>
                 <td class="border" style="text-align:center">Center</td>
                 <td class="border" style="text-align:center">Center</td>
         </tr>
         <tr>
                 <td class="border">Left</td>
                 <td class="border" style="text-align:center">Center</td>
                 <td class="border" style="text-align:center">Center</td>
         </tr>
</table>

Left	Center	Center
Left	Center	Center
Left	Center	Center

A cell can be made to span more than one column with the attribute colspan="x", where x is the number of columns you want the cell to span; the attribute for rows is, similarly, rowspan="x". So, if you want a table where one cell spans two rows and two columns, you'd write:

<table class="border">
        <tr>
                <td class="border" colspan="2" rowspan="2">First and second row, first cell</td>
                <td class="border">First row, second cell</td>
        </tr>
        <tr>
                <td class="border">Second row, second cell</td>
        </tr>
        <tr>
                <td class="border">Third row, first cell</td>
                <td class="border">Third row, second cell</td>
                <td class="border">Third row, third cell</td>
        </tr>
</table>

...and it will look like this:

First and second row, first cell		First row, second cell
First and second row, first cell		Second row, second cell
Third row, first cell	Third row, second cell	Third row, third cell

Note in the source code above that even though the table structure is still 3×3, the code on the first row has only two entries, and the second row only one entry, of <td></td>, instead of the normal three for both rows. This is because the space for the "omitted" <td>'s has already been allocated in the first row's first <td>, with colspan="2" and rowspan="2".

In other words: the basic structure of a table is always "X number of rows times X number of columns". Having cells span more than one row or column works within this basic structure, so if one cell spans two columns in a 3×3 table, one of the rows must have only two cells: one that spans just one column, and another one that spans two. It's pretty easy to make the mistake of having too many or too few rows or columns in a complex table, so make sure to check each table in the browser!

Another way besides borders to increase the legibility of big tables is to colour every second row with an alternate colour. You do it by inserting class="alt" inside the <tr> tag:

It will look like this:

1st row, 1st cell	1st row, 2nd cell	1st row, 3rd cell
2nd row, 1st cell	2nd row, 2nd cell	2nd row, 3rd cell
3rd row, 1st cell	3rd row, 2nd cell	3rd row, 3rd cell
4th row, 1st cell	4th row, 2nd cell	4th row, 3rd cell
5th row, 1st cell	5th row, 2nd cell	5th row, 3rd cell

This example table is probably too small to merit an alternate colour on every other line in actual practice, but if you have a look at this page, for example, maybe you can see how alternate colouring might help keep contents in their own line.