Docs repo structure

This repo serves as the source for the DotVVM Documentation website. Each branch corresponds to a specific version of DotVVM.

Repo structure

• Pages directory contains markdown files with text pages in the documentation.
• Controls directory contains samples for framework and library controls.
• menu.xml defines the structure of the left menu.

menu.xml

This file defines the tree structure of the docs site. The following XML elements are supported:

• DocStaticMenuItem is a link to a special page in the docs (e. g. Home)
• DocPageMenuItem is a link to a page in the Pages directory. If the element contains children, it is considered only as a "directory" and doesn't point to a markdown file. The RouteName attribute is the URL fragment, and it must also correspond to the structure of the filesystem.
• DocControlCategory element represents a controls section - this menu item will host all controls in a specified category.

<DocMenu Version="2.0">
  <DocStaticMenuItem RouteName="Home" PageName="Home" />       <!-- link to docs home page -->
  <DocPageMenuItem RouteName="section1" PageName="Section 1">  <!-- section header only -->
    <DocPageMenuItem RouteName="page1" PageName="Page 1" />    <!-- this will point to Pages/section1/page1.md file -->
    <DocControlCategory Category="builtin" />                  <!-- under this section, all controls from the "builtin" category will be listed -->
  </DocPageMenuItem>
</DocMenu>

The DocPageMenuItem can also contain LegacyPaths attribute - it can list paths of the same page in the previous version of the documentation in case the page was renamed or moved.

Also, it is possible to use the CssClass attribute, which will apply a special CSS class on the menu item to provide icon or coloring.

Pages

The Pages folder should contain Markdown files in the same structure as they are listed in the menu.xml.

Images and additional artifacts are kept in the same folder. They can be referenced in Markdown using just the filename. See an example.

The pages should follow the style guide.

Controls

The Controls folder contains subfolders for each control category:

• builtin - components included in the DotVVM framework itself
• bootstrap*- Bootstrap for DotVVM
• businesspack- DotVVM Business Pack

Each subfolder contains a folder for each control, and also metadata JSON and documentation XML files.

Directory Controls/builtin:

Button           // folder for the Button control
TextBox          // folder for the TextBox control
metadata.json    // JSON metadata about controls and properties
doc.xml          // XML documentation file

Each folder with a control has the following structure:

Directory Controls/builtin/TextBox:

sample1       // directory with Sample 1
sample2       // directory with Sample 2
control.md    // summary info about the control (required)
output.md     // info about what HTML the control renders (optional)

Each sample directory contains:

Directory Controls/builtin/TextBox/Sample1:

sample.json        // contains list of files in the sample and other metadata (required)
sample.md          // info about the sample (required)
...                // any other files listed in sample.json

Format of sample.json

{
  "files": [      // list of files in the sample
    { "name": "page.dothtml" },
    { "name": "ViewModel.cs" },
    {
      "name": "master.dotmaster",
      "replacements": [          // regex replacements that are done in the file before showing on the site
        {
          "pattern": "(\\<!.*\\<body\\>)",
          "replacement": "",
          "singleLine": true
        },
        {
          "pattern": "(\\</body\\>.*)$",
          "replacement": "",
          "singleLine": true
        }
      ]
    }
  ]
}

The .dothtml files don't have to contain the @viewModel directive - the sample generator app will add it automatically when generating runnable samples if there is exactly one viewmodel in the sample.

The .cs files don't have to contain usings and namespaces - the sample generator app will add them automatically.

doc.xml

This is a standard file generated by MSBuild when building the component DLL. The documentation site looks for comments on control classes and their properties.

• The summary text for controls is taken from the <summary> element on top of the control class.

/// <summary>
/// Represents a Bootstrap Carousel widget
/// </summary>
public class Carousel
{
   ...
}

• For code-only controls, the summary for control properties comes from the <summary> element on property declarations.

/// <summary>
/// Gets or sets the template color of the GridView.
/// </summary>
public BootstrapTableTheme TableTheme
{
    get { return (BootstrapTableTheme)GetValue(TableThemeProperty); }
    set { SetValue(TableThemeProperty, value); }
}
public static readonly DotvvmProperty TableThemeProperty =
    DotvvmProperty.Register<BootstrapTableTheme, GridView>(c => c.TableTheme, BootstrapTableTheme.Default);

• For composite controls, the <param> element of the GetControls method is used:

/// <param name="click">Gets or sets the command that will be triggered when the badge is clicked.</param>
public static DotvvmControl GetContents(
    ICommandBinding? click = null
    TextOrContentCapability textOrContentCapability
)
{
    ...
}

• For properties generated by capability, the <summary> from the property in the capability is used:

/// <summary>
/// Gets or sets the text inside the control.
/// </summary>
public ValueOrBinding<string>? Text { get; init; }

• To override the capability property summary for a composite control, use the <capability-param> element:

/// <param name="...">...</param>
/// <capability-param name="content">Gets or sets the content inside the badge.</capability-param>
public static DotvvmControl GetContents(
    ...
    TextOrContentCapability textOrContentCapability
)
{
    ...
}

metadata.json

This file is generated by DotvvmWeb.AssemblyMetadataGenerator utility from the component DLL file. The process is described in the DotvvmWeb project readme.