diff --git a/app-config.yaml b/app-config.yaml index 39527c20bd..79967842ef 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -12,3 +12,6 @@ backend: organization: name: Spotify + +techdocs: + storageUrl: https://techdocs-mock-sites.storage.googleapis.com diff --git a/plugins/techdocs/README.md b/plugins/techdocs/README.md index 36d00fc970..8ac34f1943 100644 --- a/plugins/techdocs/README.md +++ b/plugins/techdocs/README.md @@ -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 +``` diff --git a/plugins/techdocs/src/config.js b/plugins/techdocs/src/config.js deleted file mode 100644 index 296b9fc14c..0000000000 --- a/plugins/techdocs/src/config.js +++ /dev/null @@ -1,17 +0,0 @@ -/* - * Copyright 2020 Spotify AB - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -export const docStorageURL = - 'https://techdocs-mock-sites.storage.googleapis.com'; diff --git a/plugins/techdocs/src/reader/components/Reader.tsx b/plugins/techdocs/src/reader/components/Reader.tsx index c42a3657cf..a6b23bd454 100644 --- a/plugins/techdocs/src/reader/components/Reader.tsx +++ b/plugins/techdocs/src/reader/components/Reader.tsx @@ -15,6 +15,7 @@ */ import React from 'react'; +import { useApi, configApiRef } from '@backstage/core'; import { useShadowDom } from '..'; import { useAsync } from 'react-use'; import { AsyncState } from 'react-use/lib/useAsync'; @@ -30,7 +31,6 @@ import transformer, { onCssReady, sanitizeDOM, } from '../transformers'; -import { docStorageURL } from '../../config'; import URLFormatter from '../urlFormatter'; import { TechDocsNotFound } from './TechDocsNotFound'; import { TechDocsPageWrapper } from './TechDocsPageWrapper'; @@ -69,12 +69,16 @@ const useEnforcedTrailingSlash = (): void => { export const Reader = () => { useEnforcedTrailingSlash(); + const docStorageUrl = + useApi(configApiRef).getOptionalString('techdocs.storageUrl') ?? + 'https://techdocs-mock-sites.storage.googleapis.com'; + const location = useLocation(); const { componentId, '*': path } = useParams(); const [shadowDomRef, shadowRoot] = useShadowDom(); const navigate = useNavigate(); const normalizedUrl = new URLFormatter( - `${docStorageURL}${location.pathname.replace('/docs', '')}`, + `${docStorageUrl}${location.pathname.replace('/docs', '')}`, ).formatBaseURL(); const state = useFetch(`${normalizedUrl}index.html`); @@ -91,7 +95,7 @@ export const Reader = () => { const transformedElement = transformer(state.value as string, [ sanitizeDOM(), addBaseUrl({ - docStorageURL, + docStorageUrl, componentId, path, }), @@ -137,7 +141,7 @@ export const Reader = () => { }, }), onCssReady({ - docStorageURL, + docStorageUrl, onLoading: (dom: Element) => { (dom as HTMLElement).style.setProperty('opacity', '0'); }, diff --git a/plugins/techdocs/src/reader/transformers/addBaseUrl.test.ts b/plugins/techdocs/src/reader/transformers/addBaseUrl.test.ts index ceb2313b03..ce903c5d2f 100644 --- a/plugins/techdocs/src/reader/transformers/addBaseUrl.test.ts +++ b/plugins/techdocs/src/reader/transformers/addBaseUrl.test.ts @@ -41,7 +41,7 @@ describe('addBaseUrl', () => { const shadowDom = createTestShadowDom(FIXTURES.FIXTURE_STANDARD_PAGE, { preTransformers: [ addBaseUrl({ - docStorageURL: DOC_STORAGE_URL, + docStorageUrl: DOC_STORAGE_URL, componentId: 'example-docs', path: '', }), @@ -76,7 +76,7 @@ describe('addBaseUrl', () => { { preTransformers: [ addBaseUrl({ - docStorageURL: DOC_STORAGE_URL, + docStorageUrl: DOC_STORAGE_URL, componentId: 'example-docs', path: 'examplepath', }), @@ -112,7 +112,7 @@ describe('addBaseUrl', () => { { preTransformers: [ addBaseUrl({ - docStorageURL: DOC_STORAGE_URL, + docStorageUrl: DOC_STORAGE_URL, componentId: 'example-docs', path: 'examplepath/', }), diff --git a/plugins/techdocs/src/reader/transformers/addBaseUrl.ts b/plugins/techdocs/src/reader/transformers/addBaseUrl.ts index 91986db729..42ed531aea 100644 --- a/plugins/techdocs/src/reader/transformers/addBaseUrl.ts +++ b/plugins/techdocs/src/reader/transformers/addBaseUrl.ts @@ -18,13 +18,13 @@ import URLFormatter from '../urlFormatter'; import type { Transformer } from './index'; type AddBaseUrlOptions = { - docStorageURL: string; + docStorageUrl: string; componentId: string; path: string; }; export const addBaseUrl = ({ - docStorageURL, + docStorageUrl, componentId, path, }: AddBaseUrlOptions): Transformer => { @@ -38,8 +38,8 @@ export const addBaseUrl = ({ .forEach((elem: T) => { const urlFormatter = new URLFormatter( path.length < 1 || path.endsWith('/') - ? `${docStorageURL}/${componentId}/${path}` - : `${docStorageURL}/${componentId}/${path}/`, + ? `${docStorageUrl}/${componentId}/${path}` + : `${docStorageUrl}/${componentId}/${path}/`, ); elem.setAttribute( diff --git a/plugins/techdocs/src/reader/transformers/onCssReady.test.ts b/plugins/techdocs/src/reader/transformers/onCssReady.test.ts index 234100fc4b..13965bcf4b 100644 --- a/plugins/techdocs/src/reader/transformers/onCssReady.test.ts +++ b/plugins/techdocs/src/reader/transformers/onCssReady.test.ts @@ -23,7 +23,7 @@ import { } from '../../test-utils'; import { addBaseUrl, onCssReady } from '../transformers'; -const docStorageURL: string = +const docStorageUrl: string = 'https://techdocs-mock-sites.storage.googleapis.com'; jest.useFakeTimers(); @@ -45,7 +45,7 @@ describe('onCssReady', () => { preTransformers: [], postTransformers: [ onCssReady({ - docStorageURL, + docStorageUrl, onLoading, onLoaded, }), @@ -65,12 +65,12 @@ describe('onCssReady', () => { preTransformers: [], postTransformers: [ addBaseUrl({ - docStorageURL, + docStorageUrl, componentId: 'mkdocs', path: '', }), onCssReady({ - docStorageURL, + docStorageUrl, onLoading, onLoaded, }), diff --git a/plugins/techdocs/src/reader/transformers/onCssReady.ts b/plugins/techdocs/src/reader/transformers/onCssReady.ts index 2d355574b6..dd50879459 100644 --- a/plugins/techdocs/src/reader/transformers/onCssReady.ts +++ b/plugins/techdocs/src/reader/transformers/onCssReady.ts @@ -17,20 +17,20 @@ import type { Transformer } from './index'; type OnCssReadyOptions = { - docStorageURL: string; + docStorageUrl: string; onLoading: (dom: Element) => void; onLoaded: (dom: Element) => void; }; export const onCssReady = ({ - docStorageURL, + docStorageUrl, onLoading, onLoaded, }: OnCssReadyOptions): Transformer => { return dom => { const cssPages = Array.from( dom.querySelectorAll('head > link[rel="stylesheet"]'), - ).filter(elem => elem.getAttribute('href')?.startsWith(docStorageURL)); + ).filter(elem => elem.getAttribute('href')?.startsWith(docStorageUrl)); let count = cssPages.length;