{"id":22816652,"url":"https://github.com/steeltoeoss/documentation","last_synced_at":"2025-04-22T21:16:55.960Z","repository":{"id":37801485,"uuid":"204061325","full_name":"SteeltoeOSS/Documentation","owner":"SteeltoeOSS","description":"The documentation, api browser, and getting started guides used for the Steeltoe's website.","archived":false,"fork":false,"pushed_at":"2025-04-22T15:34:03.000Z","size":16940,"stargazers_count":8,"open_issues_count":37,"forks_count":22,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-22T21:16:44.047Z","etag":null,"topics":["api-browser","documentation","getting-started","hacktoberfest","steeltoe"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SteeltoeOSS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-08-23T19:52:03.000Z","updated_at":"2025-04-04T15:40:51.000Z","dependencies_parsed_at":"2024-04-19T23:25:23.047Z","dependency_job_id":"4f784614-29fa-4fc0-a136-90e65ea39110","html_url":"https://github.com/SteeltoeOSS/Documentation","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SteeltoeOSS%2FDocumentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SteeltoeOSS%2FDocumentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SteeltoeOSS%2FDocumentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SteeltoeOSS%2FDocumentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SteeltoeOSS","download_url":"https://codeload.github.com/SteeltoeOSS/Documentation/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250324707,"owners_count":21411946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-browser","documentation","getting-started","hacktoberfest","steeltoe"],"created_at":"2024-12-12T14:08:14.669Z","updated_at":"2025-04-22T21:16:55.951Z","avatar_url":"https://github.com/SteeltoeOSS.png","language":"JavaScript","readme":"# Documentation\n\n## Overview\n\nThis is the home of Steeltoe documentation and blog articles. The site uses [DocFX](https://dotnet.github.io/docfx) to convert Markdown to HTML, generate API documentation from triple-slash comments in Steeltoe and generate site navigation.\n\n## Site Contents\n\n| Path | Description\n| --- | ---\n| `/api` | API documentation\n| `/articles` | blog posts\n| `/guides` | guides for getting started with Steeltoe\n| `/template` | theming\n\n## DocFX Markdown\n\nDocFX offers an enhanced flavor of Markdown. To see examples and learn more, view the [DocFX Flavored Markdown](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html) documentation.\n\nVisual Studio Code users may find the [Docs Authoring Pack](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-authoring-pack) extension pack useful.\n\n### Links and Cross References\n\nAs 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](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html).\n\n\u003e [!NOTE]\n\u003e 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.\n\n### Page display options\n\nIn the YAML header of a page's markdown, you have options to turn page elements on or off. Below are those options.\n\n|Yaml label  |Default value  |Description   |\n|---------|---------|---------|\n|_disableToc     |false|Turn off the left hand table of contents         |\n|_disableAffix     |false|Turn off the right hand page navigation links         |\n|_disableContribution     |false|Turn off right hand link to \"edit this page\"         |\n|_disableFooter     |false|Don't show footer when guest scrolls to page bottom         |\n|_enableSearch     |true|Show the search icon         |\n|_enableNewTab     |true|All links on the page open in a new browser tab         |\n|_disableNav     |false|Do not show top navigation links         |\n|_hideTocVersionToggle|false     |Hide the version toggler in the table of contents         |\n|_noindex     |false|Do not let search engines index the page         |\n|_disableNavbar|false     |Do not show top bar of page         |\n\n## Creating a new blog post\n\nCreate 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.\n\nHere is a starter blog post:\n\n```markdown\n---\ntype: markdown\ntitle: My Very Authentic Blog Post Title\ndescription: A short description of my topic. Maybe 2 sentences long.\ndate: 01/01/2000\nuid: articles/my-very-authentic-blog-post-title\ntags: [ \"modernize\", 'something else\", \"and another thing\" ]\nauthor.name: Joe Montana\nauthor.github: jmontana\nauthor.twitter: thebigguy\n---\n\n# My Very Authentic Blog Post Title\n\nLet's talk about something really cool...\n```\n\n## Creating a new API document\n\nSimilar to the blog post, you're going to create a new markdown file, but in the `api` folder. The name needs to be URL-safe. Notice in the api folder, there is a `v2`, `v3` and `v4` subfolder. Within each of those are folders for each component. Place your content accordingly. To include the file in the table of contents, add it in `api/(version)/toc.yml`. Notice in the example below that the `topicHref` values are not absolute paths. DocFX will calculate everything at build time.\n\nAn example API doc:\n\n```markdown\n---\nuid: api/v2/circuitbreaker/hystrix\n---\n\n# Netflix Hystrix\n\nSteeltoe'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...\n\nHere is an example cross-reference link to config docs: @api/v2/configuration/cloud-foundry-provider\nOr you could link to the v3 version of this doc: @api/v3/circuitbreaker/hystrix\nOr do the same thing by providing custom link text: [view the v3 version](xref:api/v2/circuitbreaker/hystrix)\n```\n\nCorresponding entry in `api/v2/toc.yml`:\n\n```yaml\n- name: Circuit Breakers\n  items:\n    - topicHref: circuitbreaker/hystrix.md\n      name: Hystrix\n```\n\n## Installing DocFX\n\n\u003e [!IMPORTANT]\n\u003e This project currently expects DocFX version 2.59.4 to be available.\n\n### Install with Chocolatey\n\nIf you are using Windows, this is the easiest method. Run this command from an elevated shell: `choco install docfx -y --version 2.59.4`\n\n### Download from DocFX\n\n\u003e [!IMPORTANT]\n\u003e If running on Linux or OS X, you will need to [install Mono](https://www.mono-project.com/docs/getting-started/install/) and use `mono` to execute the DocFX binary.\n\n- Download DocFX [distribution](https://github.com/dotnet/docfx/releases/v2.59.4).\n- Unzip to directory of your choosing and add that directory to your `PATH`.\n- See the script in this repository at path `docfx/docfx` for an example wrapper script.\n\n## Building and running the site\n\nFor working on any non-trivial changes, there are several ways to build and run the site locally.\n\n### Basic build and run\n\nThe easiest way to build and run the site is this command: `docfx build --serve --port 8082`.\n\n### Build API docs for Steeltoe 2, 3 and 4\n\nBuilding the API docs is not required for the site to run locally.\n\nIf needed, these commands will download the Steeltoe source code and generate API documentation from the triple-slash comments in the codebase.\n\n```bash\ngit clone https://github.com/SteeltoeOSS/Steeltoe sources/v2 -b release/2.5\ngit clone https://github.com/SteeltoeOSS/Steeltoe sources/v3 -b release/3.2\ngit clone https://github.com/SteeltoeOSS/Steeltoe sources/v4 -b release/main\ngit clean -fX api\ndocfx metadata api-v2.json\ndocfx metadata api-v3.json\ndocfx metadata api-v4.json\ndocfx metadata api-all.json\n```\n\n\u003e This process can take a while to complete, will display many warnings and may increase build time in subsequent runs of `docfx build`.\n\n### Build the site docs\n\nThis documentation site is expected to run alongside Steeltoe's [main site](https://github.com/SteeltoeOSS/MainSite). 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.\n\n```bash\n# main site -\u003e https://steeltoe.io\ndocfx build --globalMetadataFiles main-site.json\n\n# main site -\u003e https://staging.steeltoe.io\ndocfx build --globalMetadataFiles main-site.staging.json\n\n# main site -\u003e http://localhost:8080\ndocfx build --globalMetadataFiles main-site.localhost.json\n```\n\n### Run local HTTP server\n\n```bash\ndocfx serve _site -p 8082\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteeltoeoss%2Fdocumentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteeltoeoss%2Fdocumentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteeltoeoss%2Fdocumentation/lists"}