Documentation

Overview

This is the home of the Steeltoe website, which hosts documentation and blog articles.

The website is built with ASP.NET Core Blazor and docfx. docfx generates API documentation from triple-slash comments in Steeltoe source code and converts Markdown documents to HTML.

Building and running the site

Follow the steps below to run/debug locally. The optional steps take longer, but provide a more complete experience.

Tip

To start fresh, delete all files that are not part of this repository (including the cloned Steeltoe sources) using the following command:

git clean -xdff

1. Optional: Build API Browser metadata (clones Steeltoe sources) and process Markdown files in docs:

   pwsh .\build\build-metadata.ps1

   See build/README.md for command-line switches.

2. Optional: Only process Markdown files in docs:

   dotnet tool restore && dotnet docfx build docs/docfx.json --warningsAsErrors true

3. Open Steeltoe.io.sln in your preferred IDE, or run from the command line:

   dotnet run --project .\src\Steeltoe.io

The site should now be running at https://localhost:8080.

Note

If this is your first time running the site and you skip steps 1 and 2, none of the static content will be processed. You will encounter InvalidFileLink warnings from files at the path docs/api and 404 errors when browsing the site.