diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index 7d5b5325cf..2fa84cebd6 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -53,4 +53,4 @@ Reader. The reason why transformers were introduced was to provide a way to transform the HTML content on pre and post render (e.g. rewrite docs links or modify css). -[Transformers API docs](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/transformers/README.md) +[Transformers API docs](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md) diff --git a/plugins/techdocs/README.md b/plugins/techdocs/README.md index 4a92c814a1..2e9365f6c6 100644 --- a/plugins/techdocs/README.md +++ b/plugins/techdocs/README.md @@ -1,45 +1,15 @@ # TechDocs Plugin -Welcome to the TechDocs plugin - Spotify's docs-like-code approach built directly into [Backstage](https://backstage.io). Watch [a video of our approach on YouTube](https://www.youtube.com/watch?v=uFGCaZmA6d4) 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](https://discord.gg/MUpMjP2) under #docs-like-code or on [our GitHub Milestone](https://github.com/spotify/backstage/milestone/15).** - ## 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](http://localhost:3000/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](./dev) directory. +Set up Backstage and TechDocs by follow our guide on [Getting Started](../../docs/features/techdocs/getting-started.md). ## 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: +TechDocs will try to read your documentation from the URL you have specified in the `techdocs storageUrl` in `app-config.yml`. -```md -# Base URL +### TechDocs Storage Api -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 `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: - -```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 -``` +The default setup of TechDocs assumes your documentation is accessed by reading a page with the format of `///`. If for some reason you want to change this it can be configured by implementing a new techdocs storage API. Do this by implementing TechDocsStorage found in `plugins/techdocs/src/api`. Add your new API to the application in `app/src/apis.ts` (or replace if it's already registered as an API). diff --git a/plugins/techdocs/src/reader/README.md b/plugins/techdocs/src/reader/README.md index 464090415c..fb9f613651 100644 --- a/plugins/techdocs/src/reader/README.md +++ b/plugins/techdocs/src/reader/README.md @@ -1 +1,20 @@ -# TODO +# TechDocs Reader + +The TechDocs reader is a component that fetches a remote page, runs transformers on it and renders it into a shadow dom. + +Currently there's no easy way to customize which transformers to run or add new ones. If that is needed you would have to fork the techdocs plugin and make your changes in that fork. + +Transformers are functions that optionally takes in parameters from the Reader.tsx component and returns a function which gets passed the DOM of the fetched page. A very simple transformer can look like this. + +```typescript +export const updateH1Text = (): Transformer => { + return dom => { + // Change the first occurance of H1 to say "TechDocs!" + dom.querySelector('h1')?.innerHTML = 'TechDocs!'; + + return dom; + }; +}; +``` + +The transformers are then registered in the Reader.tsx file. They are registered in two places, one place that runs before it's attached to the actual browser DOM (preTransformers) and once after (postTransfomers). Doing modifications is faster before it's attached, but doesn't allow us to do some things, such as attaching event listeners. diff --git a/plugins/techdocs/src/reader/transformers/README.md b/plugins/techdocs/src/reader/transformers/README.md deleted file mode 100644 index 464090415c..0000000000 --- a/plugins/techdocs/src/reader/transformers/README.md +++ /dev/null @@ -1 +0,0 @@ -# TODO