Sebastian Qvarfordt
13908d69c2
* feature(techdocs): JIT generation of techdocs * Fix linting issues * Add Techdocs tab to entity page * Added missing dep * Added missing dep * Removed duplicate dep * Better tab navigation * Update label on entity page to say docs * Fix lint issue * Move building of docs from entity to a function * feature(techdocs): JIT generation of techdocs * Fix linting issues * Add Techdocs tab to entity page * Added missing dep * Added missing dep * Removed duplicate dep * Better tab navigation * Update label on entity page to say docs * Fix lint issue * Move building of docs from entity to a function * attempt to add back react as a dep * Fixed failing test * fix(techdocs): Hopefully fixed tests * Fixed another failing test * Initial apiRef for techdocs storage * Cleaned up some code in reader * test(headertabs): add tests to HeaderTabs component * fix(headertabs): change tab mock id * fix(techdocs-generator): fix problem with macOS symlink to tmp folder * fix(lint): remove unused configApiRef * wip * Ongoing cleanups * Cleanups and fix tests * WIP cleanups * Clean up some things * Clean up some things * Added missing notice header * ts issue fixed * Add show contition to api tab Co-authored-by: Fredrik Adelöw <freben@gmail.com> Co-authored-by: Emma Indal <emmai@spotify.com>
TechDocs Plugin
Welcome to the TechDocs plugin - Spotify's docs-like-code approach built directly into Backstage. Watch a video of our approach on YouTube to learn more.
WIP: This plugin is a work in progress. It is not ready for use yet. Follow our progress on the Backstage Discord under #docs-like-code or on our GitHub Milestone.
Getting started
Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running yarn start in the root directory, and then navigating to /docs.
You can also serve the plugin in isolation by running yarn start in the plugin directory.
This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
It is only meant for local development, and the setup for it can be found inside the /dev directory.
Configuration
Custom Storage URL
TechDocs currently reads a static HTML file, generated by Mkdocs (see our packages/techdocs-container folder for more documentation) and stored on an external server, and loads that into Backstage. By default, we have set up a mock server with some example documentation sites over in Google Cloud Storage:
# Base URL
https://techdocs-mock-sites.storage.googleapis.com
# Home Page for the "mkdocs" docs
https://techdocs-mock-sites.storage.googleapis.com/mkdocs/index.html
# Home Page for the "backstage-microsite" docs
https://techdocs-mock-sites.storage.googleapis.com/backstage-microsite/index.html
Using your own setup (or ours which is being worked on as of Q3 2020), you can point it to your own server with your own hosted documentation sites. The only requirement is that it the output is from Mkdocs with the Material theme. You can always use our documentation generation tool located at packages/techdocs-container for easy setup.
To point TechDocs to your own server, simply update the techdocs.storageUrl value in your app-config.yaml file or set the environment variable APP_CONFIG_techdocs_storageUrl in your application:
git clone git@github.com:spotify/backstage.git
cd backstage/
yarn install
export APP_CONFIG_techdocs_storageUrl='"http://example-docs-site-server.com"'
yarn start