This is the home of Steeltoe documentation and blog articles. The site uses DocFX to convert Markdown to HTML, generate API documentation from triple-slash comments in Steeltoe and generate site navigation.

DocFX offers an enhanced flavor of Markdown. To see examples and learn more, view the DocFX Flavored Markdown documentation.

Visual Studio Code users may find the Docs Authoring Pack extension pack useful.

As you get familiar with DocFX, you'll notice the addition of a YAML header in the markdown files. Values in this header let you control page design, as well as set the page's UID. With this, you can create xref as well as use DocFX's @ shorthand. Learn more about linking in DocFX.

Note it should be very rare that you hardcode a link to an 'HTML' page with your markdown. Instead, use its UID and let the path get calculated, as well as get links validated when building the project.

In the YAML header of a page's markdown, you have options to turn page elements on or off. Below are those options.

Create a new .md file in the articles directory. Name the file something that is URL safe. In /articles/index.md add a shorthand link to the document as well as a short description. If the post should also be included in Steeltoe's RSS feed, add a link entry in articles/rss.xml.

Here is a starter blog post:

---
type: markdown
title: My Very Authentic Blog Post Title
description: A short description of my topic. Maybe 2 sentences long.
date: 01/01/2000
uid: articles/my-very-authentic-blog-post-title
tags: [ "modernize", 'something else", "and another thing" ]
author.name: Joe Montana
author.github: jmontana
author.twitter: thebigguy
---

# My Very Authentic Blog Post Title

Let's talk about something really cool...

Create a new markdown file in the api directory. Name the file something URL safe. In the api directory there are v2 and v3 directories. Within each of those are directories for each component. Place your content accordingly. To include the document in the Table of Contents, add it to api/(version)/toc.yml. An example API document:

An example API doc:

---
uid: api/v2/circuitbreaker/hystrix
---

# Netflix Hystrix

Steeltoe's Hystrix implementation lets application developers isolate and manage back-end dependencies so that a single failing dependency does not take down the entire application. This is accomplished by wrapping all calls to external dependencies in a `HystrixCommand`, which runs in its own...

Here is an example cross-reference link to config docs: @api/v2/configuration/cloud-foundry-provider
Or you could link to the v3 version of this doc: @api/v3/circuitbreaker/hystrix
Or do the same thing by providing custom link text: [view the v3 version](xref:api/v2/circuitbreaker/hystrix)

Corresponding entry in api/v2/toc.yml:

- name: Circuit Breakers
  items:
    - topicHref: circuitbreaker/hystrix.md
      name: Hystrix

Install DocFX using one of 2 options: download from DocFX or use Docker image.

Download DocFX distribution. Unzip to directory of your choosing and add that directory to your PATH. If running on Linux or OS X, you will need to install Mono and use mono to execute the DoxFX binary. See the script in this repository at path docfx/docfx for an example wrapper script.

You can build a Docker image with the DocFX binary and use the Powershell script docfx.ps1 to run the image. docfx.ps1 mounts the project directory in the Docker container and passes any arguments to the docfx command in the container.

To build the Docker image:

$ docker build docfx --file "docfx/Dockerfile"

Sample invocation:

$ ./docfx.ps1 --version
docfx 2.59.2.0
Copyright (C) 2022 ? Microsoft Corporation. All rights reserved.
This is open-source software under MIT License.

For working on any non-trivial changes, there are several ways to build and run the site locally.

The easiest way to build and run the site is this command: docfx build --serve --port 8082.

Building the API docs is not required for the site to run locally.

If needed, these commands will download the Steeltoe source code and generate API documentation from the triple-slash comments in the codebase.

$ git clone https://github.com/SteeltoeOSS/Steeltoe sources/v2 -b release/2.5
$ git clone https://github.com/SteeltoeOSS/Steeltoe sources/v3 -b release/3.2
$ git clean -fX api
$ docfx metadata api-v2.json
$ docfx metadata api-v3.json
$ docfx metadata api-all.json

This documentation site is interconnected with Steeltoe's main site. In order to run the two together, the appropriate main-site.json file variant is used to identify where the main site is running.

# main site -> https://steeltoe.io
$ docfx build --globalMetadataFiles main-site.json

# main site -> https://dev.steeltoe.io
$ docfx build --globalMetadataFiles main-site.dev.json

# main site -> http://localhost:9081
$ docfx build --globalMetadataFiles main-site.localhost.json

$ docfx serve _site -p 9082