Tag reference

Standard HTML tags

The following tags should be usable just as they are in regular HTML:

a, abbr, acronym, address, applet, area, article, aside, audio, b, basefont, bdi, bdo, big, blink, blockquote, br, button, canvas, caption, center, cite, code, col, colgroup, command, content, data, datalist, dd, del, details, dfn, dialog, dir, div, dl, dt, element, em, embed, fieldset, figcaption, figure, font, footer, form, frame, frameset, h1, h2, h3, h4, h5, h6, header, hgroup, hr, i, img, input, ins, isindex, kbd, keygen, label, legend, li, listing, main, map, mark, marquee, menu, menuitem, meter, nav, noembed, noscript, object, ol, optgroup, option, output, p, param, plaintext, pre, progress, q, rp, rt, rtc, ruby, s, samp, script, section, select, shadow, small, source, spacer, span, strike, strong, sub, summary, sup, table, tbody, td, template, tfoot, th, thead, time, tr, track, tt, u, ul, var, video, wbr, xmp

Attributes are passed through verbatim and not checked.

Table of contents

The Table of Contents plugin introduces one new tag:

  include-heading=true />

The table of contents takes the top level of its hierarchy from your config file. See Defining table of contents structure with file_hierarchy for details.

The titles and intra-document structure are taken from the heading nodes.

The output looks like this:

<h1>Table of Contents</h1>
<nav class="table-of-contents">
      Heading 1
        <li>Subheading 1</li>

You can optionally customize the text of the title ("Table of Contents") by adding content to the tag:

<table-of-contents>Table of Comp-Tents</table-of-contents>


You can call out a note or a warning using—wait for it—<note> and <warning>. Use no-prefix=true to omit the automatic first line of bold text.

If you want to put multiple paragraphs in an aside, you need to put the opening and closing tags in their own paragraphs. See Parser caveats.

Example 1

<note>This is a note.</note>

<note no-prefix=true>
This is another note.

This is a note.

Example 2

<note no-prefix=true>

**Another note**

This is a multi-paragraph note with a custom first line.


Another note

This is a multi-paragraph note with a custom first line.

Example 3

<warning>This is a warning.</warning>

This is a warning.

Linking to sections

You can define a "heading alias" like this:

<heading-alias name="configuration" />
# Configuring Foobar

You can then link to the section like this:

Check out the <heading-link name="configuration" /> section.

This will automatically include the heading's contents and link to it:

Check out the Configuring Foobar section.

You can set custom link text by just using the non-self-closing version:

Check out the
<heading-link name="configuration">Configuration</heading-link>

Check out the Configuration section.

Python documentation

Computer Words supports including documentation from symbol files. These can be generated for Python 3.5 like this:

python3 -m computerwords.source_parsers.python35 . mymodule \
  > docs/symbols.json
Computer words currently supports only Python 3.5 for source parsing. Adding support for more parsers is probably one of the easier things to contribute, though! To add a new Python source parser, just copy this file, make the necessary tweaks for the version you want to support, and send a pull request.

Then tell Computer Words where to find the symbol file in your config like this:

    "python": {
        "symbols_path": "./symbols.json"

(Remember, all paths in the config file are relative to the config file's directory.)

Now you can use the <autodoc-python /> tag to include source docs in your Markdown files:

    heading-level=2 />


Missing features

Why the intermediate JSON step?

Because the general interface with source parsers needs to work for languages besides Python. Languages tend to have parsers for themselves in their standard libraries; Computer Words should make use of them.