Getting Started with Documentation Generation Edit on GitHub

The StorytellerDocGen tool lives in the dotnet stdocs extension to the .Net CLI. Today, the easiest way to consume that is to create a small project at the root of your codebase repository like this example taken from the Marten project using the project.json format:

{
	"name": "Documentation",
	"frameworks":{
	    "netcoreapp1.0": {
			  "dependencies": {
				  "NETStandard.Library": "1.6.0",
				  "Microsoft.NETCore.App": {
					  "type": "platform",
					  "version": "1.0.0"
				  }
			  },
			  "imports": [
				  "dnxcore50"
			  ]
      }
    },
	
	"tools":{
		"dotnet-stdocs": {
			"version":  "1.0.0",
			"imports": ["dnxcore50"]
		}
	}
}

or in the new VS2017 format:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp1.0</TargetFramework>
    <AssemblyName>Documentation</AssemblyName>
    <PackageTargetFallback>$(PackageTargetFallback);dnxcore50</PackageTargetFallback>
    <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
    <RuntimeFrameworkVersion>1.0.4</RuntimeFrameworkVersion>
  </PropertyGroup>

  <ItemGroup>
    <DotNetCliToolReference Include="dotnet-stdocs" Version="1.0.0-alpha-442" />
  </ItemGroup>

</Project>

Once that's in place, you can run the dotnet stdocs new command to seed the very basic structure that StorytellerDocGen needs:

• layout.htm - Establishes the standard layout for the topic pages in your documentation website. See Documentation Skinning.
• splash.htm - The home page for the website. You can opt to delete this and replace it with an index.md file to just take advantage of your standard layout
• /content - Several css and js files for layout. Nothing here is absolutely necessary

Setting up StorytellerDocGen by Hand

As a concrete example, the source files for this documentation is on GitHub.

To get started with the living documentation generation, create a file structure in your code repository like this below:

• /documentation - A folder at the root of your code repository that holds all the content files and assets for the documentation. This folder name is only the default idiom, but using this name and location makes the ST.exe commands a little easier to use.

• /documentation/content - Put any css, images, or javascript files used in your documentation. Any files in the /content folder are automatically included when publishing your documentation

• /documentation/layout.htm - Establishes the general page layout for the topic files in your documentation project. See Documentation Skinning for more information on working with custom layouts.

• /documentation/splash.htm or /documentation/index.md - One way or another you need a home page for your published documentation. If you just want a simple file that uses your standard layout, use index.md directly underneath /documentation. If you have more web design ability than I do (and who doesn't?), you can opt for a splash.htm file. The splash.htm file still supports the same custom transforms described in Authoring Topics.