Project.txt is the main configuration file for your project.  It's where you tell Natural Docs which folders to scan, where to put the generated documentation, and some other settings like what the name of your project is.

You tell Natural Docs which folder to scan for source code with this line:

Source Folder: C:\My Project\Source

When you run Natural Docs it will convert any absolute paths into ones relative to the project configuration folder.  So if you keep your source code in C:\My Project\Source and make your project configuration folder C:\My Project\ND Config, the path will change to ..\Source.  This lets Project.txt remain portable across machines and play nice with version control systems.  You don't have to worry about typing relative paths though, just putting in absolute ones and letting Natural Docs convert it is fine.

You can have multiple source folders.  If you do each one should get a name to distinguish them in the documentation.  Natural Docs will make a guess as to what they should be, but you can set them manually for more control.

Source Folder: C:\My Project\Module A\Source
   Name: Module A

Source Folder: C:\My Project\Module B\Source
   Name: Module B

If you have a lot of source folders, another option is to use a higher level folder and exclude the ones you don't want instead.

Source Folder: C:\My Project

Ignore Source Folder: C:\My Project\Notes
Ignore Source Folder: C:\My Project\Test Data

Natural Docs expects source files to be encoded in Unicode by default.  It will automatically detect and handle all forms of UTF-8, UTF-16, and UTF-32.  If you have something different you can add an Encoding line to Project.txt:

Encoding: Windows-1252

This sets the default encoding for all files to Windows 1252 (Western European).  If it appears in the project information section it will be the default for all source folders.  If you put it under a Source Folder heading it will be the default for just that folder.

You can also set the character encoding for just certain file extensions:

Encoding: Macintosh *.mac

This sets the encoding for all .mac files to Macintosh (Roman/Western European).  Like before, if it appears in the project information it will apply to all source folders, but if it appears under a Source Folder heading it will only apply in that folder.

You can also set the character encoding for a folder, or file extensions within that folder:

Encoding: iso-8859-1 C:\My Project\Source\Module1
Encoding: shift_jis  C:\My Project\Source\Module1\*.txt

This sets the encoding for all files in the Module1 folder to ISO 8859-1, except for text files which are Shift JIS.  These rules take precedence over any rules for parent folders, so all .mac files appearing in Module1 are also ISO 8859-1.  You can only put Encoding lines that specify folders like this under Source Folder headings.

All operating systems may not support the same encodings.  You can see which ones are available on yours by running Natural Docs with the --list-encodings command line option.  You can use either the name or the code page number in Project.txt.

You tell Natural Docs where to put the generated documentation with this line:

HTML Output Folder: C:\My Project\Documentation

You should always give your project a title in Project.txt.  It's what appears in the header of the documentation, on its the front page, and in the HTML page titles.

Title: My Project

If you want you can also add a subtitle, which is a second, smaller line of text underneath the title, and copyright and timestamp information, which appear on the front page and in the footer.

Subtitle: Version 1.0

Copyright: Copyright (C) 2023 Me
Timestamp: Last updated month day, year

Timestamp performs the following substitutions, so if you were to use "Updated month day, year" it would turn into "Updated January 1st, 2023".  If you used "Generated mm-dd-yyyy" it would turn into "Generated 01-01-2023".

All of these properties are optional though, so you don't have to include them.

By default, when you embed images in your comments it looks for the image file relative to the source file.  So if you put (see MyImage.jpg) in C:\MyProject\Source\MyClass.cs, it will look for C:\MyProject\Source\MyImage.jpg.  However, you can tell Natural Docs to search additional folders for images with this line:

Image Folder: C:\My Project\Images

Now it will also look for C:\MyProject\Images\MyImage.jpg.  You can specify as many image folders as you want and it will search them all in order.

You can define your own home page for the documentation by adding this line to Project.txt:

Home Page: [file]

It could reference a documented source file or a HTML file.  It will replace this part of the home page.  The project title, search box, and side menu will still be visible.

Using a source file lets you write the content of the home page in Natural Docs' own syntax.  This is useful if you want to be able to easily link to parts of your code.  If you don't want to use an actual source file you can create a documented text file for this purpose.

The source file must appear in one of Natural Docs' source folders.  You can't put it in the project configuration folder.

Using a HTML file lets you do anything you want with this area.  The HTML file can be located anywhere though it's recommended that you put it in your project configuration folder.

The file must be self-contained so any CSS or JavaScript it uses should be embedded in the HTML itself.  If you need to include images, external CSS files, or external JavaScript files you should use an advanced style containing a custom home page instead.

These strings can appear anywhere in the HTML and Natural Docs will replace them with the corresponding project information.  This is useful if you want to include a timestamp that automatically updates.

• %NaturalDocs_Title%

• %NaturalDocs_Subtitle%

• %NaturalDocs_Copyright%

• %NaturalDocs_Timestamp%

Some of the options in Project.txt can be specified on the command line instead.  This is partially for compatibility with Natural Docs 1.x, as Project.txt was introduced in 2.0.  The command line is available for those that want it, but Project.txt is the recommended way of working.

Anything specified on the command line will override the settings in Project.txt.  Not only that, some will be saved into Project.txt, overwriting any conflicting settings.  This allows people who used Natural Docs 1.x to migrate easily, as it will generate a correct Project.txt for them if they run 2.0 with their old command line.  It also allows people to continue to use the command line if they choose and only use Project.txt for secondary settings like the project title or the names of source folders.

Settings are handled in four groups: source, source filtering, images, and documentation.  Specifing a setting for a group on the command line will override all the Project.txt settings for that group.  This means if you use -i to specify a source folder, Natural Docs will view that as the full list of source folders and ignore any in Project.txt that aren't also on the command line.  The same goes for the source filters if you use -xi or -xip and the generated documentation if you use -o.

Title: [text]

The name of your project.  This will appear on the front page, heading, and in the page titles of your documentation.  If you use (R) or (TM) they will be converted to their respective symbols.

Subtitle: [text]

A subtitle for your project.  This will appear on the front page and heading of your documentation.

Copyright: [text]

The copyright notice for your project.  This will appear on the front page and footer of your documentation.  If you use (C) it will be converted to the copyright symbol.

Timestamp: [text]

Text explaining when the documentation was generated.  This will appear on the front page and footer of your documentation.  The following substitutions are performed:

So if you were to use "Updated month day, year" it would turn into "Updated January 1st, 2023".  If you used "Generated mm-dd-yyyy" it would turn into "Generated 01-01-2023".

Style: [style]

The style to apply to the generated documentation.  It can be the name of a CSS file in the project configuration folder for a simple style or a subfolder that contains Style.txt for an advanced style.  Do not include ".css" if using a CSS file.

Home Page: [file]

A custom home page for the generated documentation.  It could be a documented file in one of the source folders or a HTML file in any location.  See Custom Home Pages for more information.

Encoding: [name or code page number]
Encoding: [name or code page number] *.[extension]

The character encoding source files use if it is something other than Unicode.  It can be specified as a name such as "iso-8859-1" or a code page number such as "28591".  You can see the list of encodings your system supports by running Natural Docs with the --list-encodings command line option.

Natural Docs defaults to Unicode which will handle all forms of UTF-8, UTF-16, and UTF-32.  You can set a new default for all files or you can limit it to an extension such as "*.txt".  You can use multiple Encoding lines to cover all the extensions that need them.

You can also set encodings for specific folders by adding Encoding lines in Source Folder sections.

Source Folder: [path]
   Name: [name]

Specifies a folder which will be searched for source files.  If you have more than one, add the Name property to set how it will show up in the menu.

Encoding: [name or code page number]
Encoding: [name or code page number] *.[extension]
Encoding: [name or code page number] [folder]
Encoding: [name or code page number] [folder]\*.[extension]

The character encoding source files use if it's something other than Unicode.  It can be specified as a name such as "iso-8859-1" or a code page number such as "28591".  You can see the list of encodings your system supports by running Natural Docs with the --list-encodings command line option.

Natural Docs defaults to Unicode which will handle all forms of UTF-8, UTF-16, and UTF-32.  You can set a new default for all files in this folder, limit it to an extension such as "*.txt", limit it to a subfolder, or limit it to extensions in a subfolder.  You can use multiple Encoding lines to cover all the subfolders and extensions that need them.

Ignore Source Folder: [path]

Tells Natural Docs to skip this folder when scanning files.

Ignore Source Folder Pattern: [pattern]

Tells Natural Docs to skip all folder names which match this pattern when scanning files.  ? matches a single character, * matches zero or more characters.  It applies to the entire folder name, so "cli" will not match "client", although "cli*" will.

The data folders of common version control systems (.git, .svn, .cvs, .hg) are ignored automatically.  You do not have to specify them here.

Image Folder: [path]

Specifies a folder which will be searched for image files.  They can be referenced in comments with (see filename.jpg).

HTML Output Folder: [path]
   [Project Information]

Generates HTML documentation in the specified folder.

If you want, you can also include any of the project information properties under this line to have them apply to just that folder.

Tab Width: [width]

The number of spaces tabs should be expanded to.

Documented Only: [yes|no]

Whether only documented code elements should appear in the output.  Defaults to no.

Auto Group: [yes|no]

Whether groups should automatically apply to you code.  Defaults to yes.