Natural Docs allows you to create your own style for the generated HTML, or you can just make adjustments to the default one.  There's two ways to do it depending on how much you want to change: a simple style, where you're just adding a single CSS file on top of the default, or an advanced style, where you can include multiple images, CSS, and JavaScript files.

In both cases you apply the style to your project by using the Style property in Project.txt or the -s command line option.

A simple style is just a single CSS file in your project configuration folder.  If you create the file Red.css, you use the name "Red" in Project.txt or on the command line to apply it.  Your documentation will have the default style applied and then your file added to override any settings you want.

This makes it very easy to make small changes.  If you only want to add colors to prototypes or change the syntax highlighting this is the fastest way to do it.  If you want to do a more elaborate redesign of the appearance you may want to use an advanced style instead.

An advanced style is a subfolder in your project configuration folder that contains a Style.txt file.  If you have a subfolder Red that contains Style.txt, you would use the name "Red" in Project.txt or on the command line to apply it.

To get started, create the subfolder in your project configuration folder and leave it empty.  Change Project.txt or the command line to use the folder name as the name of the style and run Natural Docs.  It will create a starter Style.txt in that folder for you.

The style will be set to inherit Default, which means anything you add will be on top of the default style with all its CSS and images.  If you'd like to start from scratch visually change the Inherit line to use DefaultJS instead.  This provides only the JavaScript that makes the documentation function but none of the visual formatting.

Put the files you want to use in the subfolder you created for your style.  Any CSS, JavaScript, JSON, images, and web font files in there will be automatically copied to the output folder.  The folder hierarchy is preserved, so if you have an images subfolder and your CSS file is in the style's root folder you can reference them with url("images/mypicture.jpg").  If you inherit from Default and want to reference its resources you can use url("../Default/images/search.png").

CSS and JavaScript are not automatically linked to the HTML files though.  You have to add them with Link lines in Style.txt like "Link: MyStyle.css".  If you want to have some JavaScript execute automatically you can also add an OnLoad handler with "OnLoad: MyFunction();".

You can choose to limit JavaScript links and OnLoad statements to certain types of pages.  They can be limited to just the frame page, which handles the header, footer, menu, summary, and search, or to content pages, which is the documentation in the rightmost panel, or to the home page.  You would do this with "Content Link: MyStyle.css" or "Frame Onload: MyFunction()".  If you do not specify a page type they will apply to every page.

CSS files can only be linked to every page.  You can't limit them to certain page types.

A Natural Docs style can contain more than one theme, which allows the person reading to choose which appearance they prefer.  The default style includes Light, Dark, and Black themes.  You can choose them by clicking the moon icon next to the search box.

There are also auto themes which will automatically switch between two depending on whether the operating system is in light or dark mode, provided both your browser and your operating system support that.

By default any customizations you make will apply to the Light theme.  If you'd like to make changes to the Dark and Black themes just add .DarkTheme and .BlackTheme before the CSS rules.  So if you changed the color of .SHComment you could also change the color of ".DarkTheme .SHComment" and ".BlackTheme .SHComment".

If you'd like your documentation to always use one theme instead of offering a choice, select Light, Dark, or Black as the style.  If you already have a custom simple style add the rule "#NDThemeSwitcher { display: none !important; }" to your CSS.  If you already have a custom advanced style edit Style.txt to inherit from Light, Dark, or Black instead of Default.

If you'd like customize the list of themes available make an advanced style and call NDThemes.SetAvailableThemes() from Frame OnLoad in Style.txt.  The below example would set the themes to Red, Dark Red, and Auto Red/Dark Red.  See the documentation for NDThemes.SetAvailableThemes() for more information.

NDThemes.SetAvailableThemes([
   [ "Red Theme", "Red" ],
   [ "Dark Red Theme", "DarkRed" ],
   [ "Auto Red/Dark Red", "Auto:Red/DarkRed"]
]);

Natural Docs has different prototype background colors for each type: functions are gray, properties are blue, variables are yellow, etc.  However, if you create your own comment types and then include prototypes for them, they default to black and white.  You can use these settings to give color to your custom prototypes.

The CSS class you need is T plus the name of your comment type using only A-Z.  Numbers, spaces, and symbols are stripped out, so if your custom comment type is called Sound Effect its CSS class would be TSoundEffect.  If removing these characters doesn't give a good result you can also manually set the Simple Identifier property in Comments.txt and add a T to that.

.TSoundEffect .NDPrototype,
.TSoundEffect .SuEntryIcon,
.TSoundEffect .SeEntryIcon {
    background-color: #F0F0F0;
    border: 1px solid #C7C7C7;
    }

NDPrototype is for prototypes appearing in the page content, whereas SuEntryIcon and SeEntryIcon are for the color swatches that appear in the summary and search results respectively.

If you'd like to use your own syntax highlighting style instead of the one Natural Docs provides, set the fonts and colors on these CSS classes:

So for example if you wanted comments to be green and in italics, you would include this in your CSS:

.SHComment {
   color: #008000;
   font-style: italic;
   }

If you want to create a home page for one project using a self-contained HTML file, a source file, or a text file with Natural Docs content it would be easier to use the home page option in Project.txt.

If you want to create a home page as part of a style that can be used with multiple projects, or if it needs images, external CSS files, or external JavaScript files then you need to use an advanced style.  You would create one, create a custom HTML file to serve as the home page, and then add this line to Style.txt:

Home Page: [file]

The HTML file will replace this part of the home page.  The project title, search box, and side menu will still be visible.

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%

Beyond that the HTML file is unaltered, so you would have to manually link other content files to it.  Any Home Link and Home OnLoad statements in Style.txt won't apply to it.  The style's folder hierarchy is preserved in the output, so if you have an images subfolder and your HTML file is in the style's root folder you can reference them with "images/mypicture.jpg".  If you inherit from Default and want to reference its resources you can use "../Default/images/search.png".

The complete CSS structure of the output is documented here.

Inherit: [style]

Inherit the settings of another style.  All of its settings will be applied before yours.  You can add this line multiple times to inherit more than one.

If you just want to make some changes to the default style, inherit Default.  If you're building your own page design from scratch but want to keep the default JavaScript functions, inherit DefaultJS.  This will include the code but not the CSS or images.

Link: [file]
Frame Link: [file]
Content Link: [file]
Home Link: [file]

Links a .css, .js, or .json file to the generated HTML pages via link or script tags.  You can link JavaScript files to just the frame page, which handles the header, footer, menu, summary, and search, or to content pages, which is the documentation in the rightmost panel, or to the home page, though this only applies to the default home page and not custom ones.  If you do not specify a page type it will be linked to every page.  CSS files can only be linked to every page.

While all files in your style folder will be copied to the output folder automatically, they are not linked automatically.  Since JavaScript files can be loaded dynamically and CSS files can be imported from other ones, you must explicitly link the ones you want.

OnLoad: [statement]
Frame OnLoad: [statement]
Content OnLoad: [statement]
Home OnLoad: [statement]

Adds a JavaScript statement to the page's OnLoad handler.  You can add it to just the frame page, which handles the header, footer, menu, summary, and search, or to content pages, which is the documentation in the rightmost panel, or to the home page, though this only applies to the default home page and not custom ones.  If you do not specify a page type it will be added to every page.

The OnLoad statement is limited to a single line.  If you have a lot of code it's recommended that you make it a function in a separate .js file, link that file, and then call the function from this statement rather than trying to cram it all on this line.

Home Page: [file]

A HTML file to serve as the home page for the style.  See Custom Home Pages for more information.