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.
| Path | Description |
|---|---|
/api |
API documentation |
/articles |
blog posts |
/guides |
guides for getting started with Steeltoe |
/template |
theming |
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.
| Yaml label | Default value | Description |
|---|---|---|
| _disableToc | false | Turn off the left hand table of contents |
| _disableAffix | false | Turn off the right hand page navigation links |
| _disableContribution | false | Turn off right hand link to "edit this page" |
| _disableFooter | false | Don't show footer when guest scrolls to page bottom |
| _enableSearch | true | Show the search icon |
| _enableNewTab | true | All links on the page open in a new browser tab |
| _disableNav | false | Do not show top navigation links |
| _hideTocVersionToggle | false | Hide the version toggler in the table of contents |
| _noindex | false | Do not let search engines index the page |
| _disableNavbar | false | Do not show top bar of page |
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.
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: HystrixNote
This project currently expects DocFX version 2.59.4 to be available.
If you are using Windows, this is the easiest method. Run this command from an elevated shell: choco install docfx -y --version 2.59.4
Important
If running on Linux or OS X, you will need to install Mono and use mono to execute the DocFX binary.
- Download DocFX distribution.
- Unzip to directory of your choosing and add that directory to your
PATH. - See the script in this repository at path
docfx/docfxfor an example wrapper script.
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.jsonThis process can take a while to complete, will display many warnings and may increase build time in subsequent runs of
docfx build.
This documentation site is expected to run alongside Steeltoe's main site. In order to run the two together, first use the instructions from the MainSite project to start that site, then use the appropriate main-site.json file variant described below to identify where the main site is running.
# main site -> https://steeltoe.io
docfx build --globalMetadataFiles main-site.json
# main site -> https://staging.steeltoe.io
docfx build --globalMetadataFiles main-site.staging.json
# main site -> http://localhost:8080
docfx build --globalMetadataFiles main-site.localhost.jsondocfx serve _site -p 8082
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent