Natural Docs Version 0.9 CSS Guide |
CSS GuideIt’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
Content StructureAll 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 Summaries. Summaries 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
Menu StructureEverything 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
Summary StructureEverything 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
Link StructureAll 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 StylesIndex StructureEverything 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
|