CSS Guide

It’s important to understand the internal HTML file structure and styles in order to design your own CSS style for Natural Docs.  If you’re content with the default styles, there’s no need to read this document. 

The diagrams are designed for clarity.  In the actual HTML, you’d obviously see “<pre class=CCode></pre>” instead of “<pre CCode></pre CCode>”.  If there’s no element in the diagram tag, for example “<CTitle></CTitle>”, that means you shouldn’t rely on what HTML element it is.  Just refer to them as .Style in your CSS file instead of Element.Style. 

Summary
It’s important to understand the internal HTML file structure and styles in order to design your own CSS style for Natural Docs.
All the content of a given file is contained in a single Content.
Everything is enclosed in a single Menu.
Everything is enclosed in a single Summary.
All links to symbols have a type style prefixed with L.
Everything is enclosed in a single Index.

Content

Content Structure

All the content of a given file is contained in a single Content.  All other content styles are prefixed with a C. 

Each piece of content is a CTopic, and inside each of those is the type.  For example, CFunction for a function.  Inside that are analogues to all the top-level NDMarkup tags: CHeading, CParagraph, etc.  Styles like CParagraph exist so that you only style explicit NDMarkup paragraphs, and not any p that is a descendant of Content

In addition to the top-level NDMarkup tags, you also have CPrototype, CTitle, and SummariesSummaries are described in their own section. 

<Content>

    <CTopic>
        <CType (CFunction, CItem, etc.)>

            <CTitle>
                Topic title
            </CTitle>

            <CPrototype>
                Prototype
            </CPrototype>

            <p CParagraph>
                Paragraph
            </p CParagraph>

            <CHeading>
                Heading
            </CHeading>

            <pre CCode>
                Code
            </pre CCode>

            <ul CBulletList>
                <li>
                    Bullet item
                </li>
            </ul CBulletList>

            <table CDescriptionList>
                <tr>
                    <td CDLEntry>
                        Entry
                    </td CDLEntry>
                    <td CDLDescription>
                        Description
                    </td CDLDescription>
                </tr>
            </table CDescriptionList>

            <Summary> (See it's section)

        </CType (CFunction, CItem, etc.)>
    </CTopic>

</Content>

Take advantange of the CSS inheritance model.  For example, you can style all titles via .CTitle, and you can style specific titles with .CType .CTitle. 

Content Styles

ContentOne Content surrounds all CTopics. 
CTopicAn individual topic. 
CTitleThe title of a topic. 
CPrototypeA prototype. 
CParagraphA paragraph.  Is implemented with a p. 
CHeadingA heading. 
CBulletListA bullet list.  Is implemented with a ul. 
CCodeA section of code.  Is implemented with a pre. 
CDescriptionListA description list, which is the type of list you’re reading right now.  Is implemented with a table. 
CDLEntryA description list entry, which is the left side. 
CDLDescriptionA description list description, which is the right side. 
CMainThe main topic. 
CClassA class topic. 
CSectionA section topic. 
CFileA file topic. 
CGroupA group topic. 
CFunctionA function topic. 
CVariableA variable topic. 
CGenericA generic topic. 
CClassListA class list topic. 
CFileListA file list topic. 
CFunctionListA function list topic. 
CVariableListA variable list topic. 
CGenericListA generic list topic. 

Menu

Menu Structure

Everything is enclosed in a single Menu.  All other menu styles are prefixed with an M. 

The title is an MTitle and will always be at the beginning of the Menu if it exists.  If a subtitle exists as well, it will appear as an MSubTitle inside MTitle.  Subtitles aren’t allowed without titles.  Every other entry in the menu is contained in a MEntry, inside of which there’s the type, such as MFile and MGroup.  Inside of that is the content.  With MGroups, there’s also a section inside called MGroupContent which can contain more entries.  Here’s the diagram:

<Menu>

    <MTitle>
        Menu title

        <MSubTitle>
            Menu sub title
        </MSubTitle>

    </MTitle>

    <MEntry>
        <MFile>
            <a href>File</a href>
        </MFile>
    </MEntry>

    <MEntry>
        <MText>
            Text
        </MText>
    </MEntry>

    <MEntry>
        <MLink>
            <a href>Link</a href>
        </MLink>
    </MEntry>

    <MEntry>
        <MGroup>
            <a href>Group</a href>
            <MGroupContent>

                (MEntries)

            </MGroupContent>
       </MGroup>
    </MEntry>

</Menu>

The MFile entry that’s currently selected will have the #MSelected ID, so you can reference it in CSS via .Menu .MFile#MSelected. 

Menu Styles

MenuOne Menu holds the entire menu. 
MTitleThe title of the menu. 
MSubTitleThe subtitle of the menu.  Will appear within MTitle
MEntryThe parent container of MFile and MGroup entries. 
MFileA file entry. 
MGroupA group entry. 
MGroupContentA container for a MGroups content. 
MTextA plain text entry. 
MLinkAn external link entry. 
#MSelectedThe ID of the currently selected MFile

Summaries

Summary Structure

Everything is enclosed in a single Summary.  All the other summary styles are prefixed with an S. 

STitle holds the actual word “Summary” and SBorder and STable hold the content.  SBorder exists because different browsers apply table padding attributes in different ways.  STable exists as a class to separate the main table from any other tables that may be necessary.  Here’s a diagram:

<Summary>

    <STitle>
        Title
    </STitle>

    <SBorder>
        <table STable>
            ...
        </table STable>
    </SBorder>

</Summary>

On to the table content.  Cells may have the SMarked class, which means they should be tinted for easier readablity. 

Since we many attributes left to apply, they’re done with a kludgy mess of styles within each cell.  It’s hacky and verbose, but it works and is compatible everywhere.  We apply the type, whether it’s an entry or a description, and if it’s in a group or class as shown below:

<tr>
    <td SMarked?>

        <SType (SFunction, SClass, etc.)>
            <SEntry>
                <SInClass/Section>? <SInGroup>?

                    <a href>Entry</a href>

                 </SInGroup>? </SInClass/Section>?
            </SEntry>
        </SType>

    </td SMarked?>
    <td SMarked?>

        <SType (SFunction, SClass, etc.)>
            <SDescription>
                <SInClass/Section>? <SInGroup>?

                    Description

                </SInGroup>? </SInClass/Section>?
            </SDescription>
        </SType>

    </td SMarked?>
</tr>

SInGroup, SInClass, and SInSection exist to allow indenting.  They’re there in their current arrangement (all three “there”s in one sentence :) because implementing it as nested tables, while structurally cleaner, won’t allow the desciptions to line up on the right throughout the entire summary. 

Use the power of CSS’s inheritance rules to specify styles.  For example, to set the style of a group entry, apply it to .SGroup .SEntry.  However, you could also apply a style to both the group’s entry and description by applying the style to .SGroup.  Or, you could apply a style to all the entries by applying it to .SEntry.  And so on. 

Summary Styles

SummaryThe topmost style containing the entire summary. 
STitleContains the summary title, which is the part that actually says “Summary”. 
SBorderSurrounds STable, since some browsers can’t do table padding right.  A hack, I know. 
STableThe actual summary table.  This class separates it from other layout tables that may appear. 
SMarkedA class applied to cells that should have a slightly different color than the rest of the cells to make it easier to read. 
SEntryThe entry (left) side of the table. 
SDescriptionThe description (right) side of the table. 
SInGroupSurrounding entries and descriptions that are part of a group. 
SInClassSurrounding entries and descriptions that are part of a class. 
SInSectionSurrounds entries and descriptions that are part of a section. 
SMainThe main summary. 
SClassFor class summaries. 
SSectionFor section summaries. 
SFileFor file summaries. 
SGroupFor group summaries. 
SFunctionFor function summaries. 
SVariableFor item summaries. 
SGenericFor generic summaries. 
SClassListFor class list summaries. 
SFileListFor file list summaries. 
SFunctionListFor function list summaries. 
SVariableListFor variable list summaries. 
SGenericListFor generic list summaries. 

Links

Link Structure

All links to symbols have a type style prefixed with L.  The only exceptions are summary entries; summary descriptions use them as well. 

<a LType (LFunction, LClass, etc.)>
    Link
</a LType (LFunction, LClass, etc.)>

You can use this to make links to different symbols appear in different styles.  For example, making .LClass bold will make all links to classes bold, except when appearing in summary entries.  You can combine this with other styles to be even more specific.  For example, you can apply a style to function links appearing in summary descriptions with .SDescription .LFunction. 

Link Styles

LClassLink to a class. 
LSectionLink to a section. 
LFileLink to a file. 
LGroupLink to a group. 
LFunctionLink to a function. 
LVariableLink to a item. 
LGenericLink to a generic. 
LClassListLink to a class list. 
LFileListLink to a file list. 
LFunctionListLink to a function list. 
LVariableListLink to a variable list. 
LGenericListLink to a generic list. 

Indexes

Index Structure

Everything is enclosed in a single Index.  All index styles are prefixed with an I. 

<Index>

    <IPageTitle>
        Page Title
    </IPageTitle>

    <INavigationBar>
        A - <a href>B</a href> - C ...
    </INavigationBar>

    <IEntry>
        <ISymbol>
            <a href>Symbol</a href>
        </ISymbol>,
        <IParent>
            Class
        </IParent>
    </IEntry>

    <IEntry>
        <ISymbol>
            Symbol
        </ISymbol>
        <ISubIndex>
            <IEntry>
                <IParent>
                    <a href>Class</a href>
                </IParent>
            </IEntry>
            ...
        </ISubIndex>
    </IEntry>

    <IEntry>
        <ISymbol>
            Symbol
        </ISymbol>
        <ISubIndex>
            <IEntry>
                <IParent>
                    Class
                </IParent>
                <ISubIndex>
                    <IEntry>
                        <IFile>
                            <a href>File</a href>
                        </IFile>
                    </IEntry>
                    ...
                </ISubIndex>
            </IEntry>
            ...
        </ISubIndex>
    </IEntry>

</Index>

Every index entry is an IEntry followed by a type.  If there’s only one class and definition file for a symbol, it gets the link.  However, if there’s more of either, they get broken out into ISubIndex entries.  A IParent subindex can be broken out yet again into an IFile subindex. 

It’s called IParent instead of <IClass> because class entries are <ISymbols>.  IParents are only used when the symbol has a class.  If the symbol is a class, the symbol is global. 

Index Styles

IndexSurrounds the entire index. 
IPageTitleThe page title. 
INavigationBarThe navigation bar. 
IEntryAn entry in the index. 
ISymbolThe entry symbol. 
IParentThe entry parent class.  If the entry is a class, this isn’t defined because classes are global and don’t have parent classes.  This is why it’s called IParent instead of IClass; hopefully it’s less confusing. 
IFileThe file the entry is defined in. 
ISubIndexSurrounds all IEntry’s in a sub-index.