paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 37 Packages Projects Releases Wiki Activity

techdocs: set custom docStorageUrl via appConfig (#1575)

Browse Source 
* feat(techdocs): read docStorageUrl from appConfig

* docs: updated techdocs plugin README to mention custom baseurl

* fix: added config file

* fix: use JSON in env variable

* fix: add to app-config.yaml

* typescript wrestling

* Nicer config handling

* fix: switch to using useApi(configApiRef)

* docs: corrected to new config name

* docs: mention app-config.yaml config option

* fix: removed unused dep @backstage/config

Co-authored-by: Sebastian Qvarfordt <s.qvarfordt@gmail.com>
This commit is contained in:
Bilawal Hameed
2020-07-10 10:48:46 +02:00
committed by GitHub
parent e25ac814ac
commit 3d4fcc4559
8 changed files with 57 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/techdocs/README.md
+32
View File
@@ -15,3 +15,35 @@ Your plugin has been added to the example app in this repository, meaning you'll
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](/dev) directory.
## Configuration
### Custom Storage URL
TechDocs currently reads a static HTML file, generated by Mkdocs (see our `plugins/techdocs/mkdocs/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:
```md
# 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](https://mkdocs.org) with the Material theme. You can always use our documentation generation tool located at `plugins/techdocs/mkdocs/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:
```bash
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
```