Multiple consecutive lines of text are combined into a single paragraph.  To start a new paragraph, skip a line.

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

This is the second paragraph.

Put asterisks around text you want to bold and underscores around text you want to underline.  You can put underscores in between each underlined word if you want to, but it's not required.

This is *bold text*.

This is _underlined text with spaces_.

This is _underlined_text_with_underscores_.

To make a heading you must skip a line, write the heading in title-case, and end it with a colon.

Parameters:

   This is where you would describe the parameters.

Returns:

   This is where you would describe the return value.

See Also:

   This is where you would include relevant links.

You are not limited to specific headings so you can use any words you want.

The blank lines beneath the headings are not required, nor are the indents, so these would work as well:

Parameters:
This is where you would describe the parameters.

Returns:
This is where you would describe the return value.

See Also:
This is where you would include relevant links.

Title-case means the first and last words are capitalized, as well as almost all the other words except for small ones like "and" and "the".  Think of the way you would write the title of a book.  These headings are in title-case:

Parameters:

This or That:

A Day in the Life:

These lines are not, so Natural Docs will treat them as plain text:

You do it like this:

or:

If you ever want to force a line to be a heading even if it doesn't appear in title-case, end it with two colons.

This is a heading even though it's not in title-case::

The heading "Parameters" is special.  If you are documenting a function, have a parameters heading, and then document the parameters in a definition list underneath it, Natural Docs will automatically include each parameter's type underneath it.

/* Function: MyFunction
 *
 * Parameters:
 *
 *    x - Description of x.
 *    y - Description of y.
 *    z - Description of z.
 */
void MyFunction (int x, string y, Counter z)
   { ... }

You can also use Params, Arguments, Args, or their singular forms for the heading.

You make a link by putting what you want to link to in angle brackets.

See function <Multiply>.

Links follow the same scoping rules as their programming languages.  If you're in the documentation for a class, you can link to another member with just <Member>.  However, if you're in the documentation for a different class, you'd have to use <Class.Member>.  You can also use :: or -> in place of the dot.

Relative links work as well, so if you're in class A.B.C.D and want to link to class A.B.E.F, you can just use <E.F>.

For languages with full support, most "using" statements work for the documentation as well.  So if you want to link to class A.B.C.D and the file has a "using A.B.C" statement you can just use <D>.

Plurals and possessives are supported both inside and outside the angle brackets.  Having them outside the angle brackets would look like this:

Links to <Object>s and <Object>'s value.

They also work inside the angle brackets, allowing them to read more easily in a sentence:

Links to <Objects> and <Object's> value.

In both the above cases, the link will still to go the same place as if you had just written <Object>.

Outside of the brackets Natural Docs only supports s, es, and 's.  Inside of the brackets Natural Docs supports virtually all English-language forms of plurals.  <Foxes>, <Fox's>, <Foxes'> will all link to Fox.  <Children>, <Mice>, <Alumni>, <Indices>, <Amoebae>, <Teeth>, etc. will all link to their respective singulars.

It's the ending that matters, so you can write <ObjectChildren> or <DatabaseIndices> and they will link to <ObjectChild> and <DatabaseIndex> respectively.  However, if there's something literally called ObjectChildren it will link to that before ObjectChild.

URLs and e-mail addresses will be detected automatically.  They can be surrounded by angle brackets but it's not required.

Visit http://www.website.com or send messages to email@address.com.

Visit <http://www.website.com> or send messages to <email@address.com>.

E-mail addresses look and act like regular links but the HTML is obfuscated to help protect them from spam crawlers.

You can create named links by putting the text, either "at" or a colon, and then the address in the angle brackets.

Visit <the website: http://www.website.com> or <e-mail me at email@address.com>.

If you have multiple functions that only differ by their parameters, you can include their types or parameter names in parentheses to link to a specific one.

// Function: MyFunction
void MyFunction (float f) { ... }

// Function: MyFunction
void MyFunction (int x, int y) { ... }

// Topic: Notes
// You can link by type with <MyFunction(int, int)> or
// by parameter name with <MyFunction(x, y)>.

This is not required, so you can still write <MyFunction> and it will link to the first one.

You can add bullet lists by starting a line with a dash, an asterisk, an o, or a plus.  The content can span multiple lines so to end it you have to skip a line.

- Bullet one.
- Bullet two.
  Bullet two continued.
- Bullet three.

Some text after the bullet list.

You can have multiple levels as long as each one is indented at least two spaces more than the previous one.  You can also have multiple paragraphs as long as they're indented two spaces from where the bullet was.

* Level one.

  * Level two, first paragraph.
    Level two, first paragraph continued.

    Level two, second paragraph.

      * Level three.

Definition lists are lines in the format "item - definition".  Like bullet lists they continue until you skip a line and you can have multiple paragraphs in the definition if they're indented.

Item 1 - The first paragraph.
         The first paragraph continued.

         The second paragraph

Item 2 - The first paragraph.
  The first paragraph continued.

  The second paragraph.

Some text after the definition list.

If you're documenting a function and put a definition list under a heading called Parameters, Natural Docs will match any items in the list with parameters in the prototype and include their types automatically.

/* Function: MyFunction
 *
 * Parameters:
 *
 *    x - Description of x.
 *    y - Description of y.
 *    z - Description of z.
 */
void MyFunction (int x, string y, Counter z)
   { ... }

You can also use Params, Arguments, Args, or their singular forms for the heading.

You can embed images into your documentation by writing (see image.jpg) in your comments.  There are two ways to do it:

// If you put it in the middle of a paragraph like this (see logo.svg) it will
// become a captioned image after the paragraph.

// If you give it its own paragraph like this, it will simply be replaced by
// the image.
//
// (see logo.svg)
//
// It needs to be separated from other paragraphs by blank lines.

You can use PNG, GIF, JPG, SVG, and BMP files.  You can include part of a path, such as (see images/diagram.svg).  By default this is relative to the source file the comment appears in, but you can also specify image folders in Project.txt and on the command line with -img.  It will search all these locations when looking for the image.

To add a section of code or plain text, start a line with at least three dashes, equals signs, or underscores followed by "Code", "Text", or a programming language name.  You can optionally follow that with more of the same symbol.  The section will continue until there's another line of at least three of the same symbol.

--- Code
int x = 12;
int y = 0;
---

==== Perl ====
my $x = 12;
my $y = 0;
==============

___ Text ____________

This is plain text.
___

Code blocks will have syntax highlighting applied for the language of the file it appears in.  If you use a language name, syntax highlighting will be applied for that language no matter where it appears.  If you use Text there will be no syntax highlighting.

int x = 12;
int y = 0;

my $x = 12;
my $y = 0;

This is plain text.

You can also switch from one mode to another without closing each block individually.

------- C# -------
int x = 12;
int y = 0;
------ Perl ------
my $x = 12;
my $y = 0;
------ Text ------
This is plain text
------------------

Some languages have aliases you can use instead of the full language name.  For example, you can write JS instead of JavaScript and VB instead of Visual Basic.  These are defined in Languages.txt.

You can also add individual lines of text by starting each one with >, |, or :.  There will be no syntax highlighting applied though.

This is a normal paragraph.

> int x = 12;
> int y = 0;

This is a normal paragraph.

int x = 12;
int y = 0;

In Natural Docs 1.x code blocks were designated with (start code) and (end) lines.  This is still supported for compatibility, though it's recommended you use the new syntax going forward.

(start code)
int x = 12;
int y = 0;
(end)

The legacy syntax was also extended so you could use language names with it, such as (start C#) or just (C#).  The current block syntax also supports legacy keywords, so you could use "--- Start C#" and "--- End" if you wanted to.

You can add prototypes directly to your comments by using the code syntax with the Prototype keyword.  This is useful for documenting things that cannot easily be documented otherwise, such as the columns and indexes of database tables.

Database Column: MyColumn

    --- Prototype ---
    MyColumn INTEGER PRIMARY KEY NOT NULL
    -----------------

    Description of MyColumn