diff --git a/docs/features/techdocs/FAQ.md b/docs/features/techdocs/FAQ.md index 8c716313bb..cae0288889 100644 --- a/docs/features/techdocs/FAQ.md +++ b/docs/features/techdocs/FAQ.md @@ -6,14 +6,11 @@ sidebar_label: FAQ This page answers frequently asked questions about [TechDocs](README.md). -_Got a question that you think others might be interested in knowing the answer -to? Edit this file -[here](https://github.com/spotify/backstage/edit/master/docs/features/techdocs/FAQ.md)._ - ## Technology - [What static site generator is TechDocs using?](#what-static-site-generator-is-techdocs-using) - [What is the mkdocs-techdocs-core plugin?](#what-is-the-mkdocs-techdocs-core-plugin) +- [Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc)?](#does-techdocs-support-file-formats-other-than-markdown-eg-rst-asciidoc-) #### What static site generator is TechDocs using? @@ -30,3 +27,10 @@ package is a MkDocs Plugin that works like a wrapper around multiple MkDocs plugins (e.g. [MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as well as a selection of Python Markdown extensions that TechDocs supports. + +#### Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc) ? + +Not right now. We are currently using MkDocs to generate the documentation from +source. So, they have to be in Markdown format. However, in future we want to +support other alternatives to MkDocs. That will make it possible to use other +file formats. diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index a7af6cc503..03f3d452f4 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -8,16 +8,21 @@ sidebar_label: Overview -Wait, what is TechDocs? TechDocs is Spotify’s homegrown docs-like-code solution -built directly into Backstage. Today, it is now one of the core products in -Spotify’s developer experience offering with 2,400+ documentation sites and -1,000+ engineers using it daily. +TechDocs is Spotify’s homegrown docs-like-code solution built directly into +Backstage. This means engineers write their documentation in Markdown files +which live together with their code. + +Today, it is one of the core products in Spotify’s developer experience offering +with 2,400+ documentation sites and 1,000+ engineers using it daily. Read more +about TechDocs and the philosophy in its +[announcement blog post](https://backstage.io/blog/2020/09/08/announcing-tech-docs). +🎉 ## Features -- A centralized place to discover documentation. +- A centralized place to discover and read documentation. -- A clear end-to-end docs-like-code solution. (_Coming soon in V.1_) +- A clear end-to-end docs-like-code solution. - A tightly coupled feedback loop with the developer workflow. (_Coming soon in V.3_) @@ -44,7 +49,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and #### TechDocs V.0 - As a user I can navigate to a manually curated docs explore page. -- As a user I can navigte to and read mock documentation that is manually +- As a user I can navigate to and read mock documentation that is manually uploaded by the TechDocs core team. #### TechDocs V.1 @@ -101,7 +106,3 @@ more to come... https://github.com/spotify/backstage/blob/master/packages/techdocs-container [techdocs/cli]: https://github.com/spotify/backstage/blob/master/packages/techdocs-cli - -## TechDocs Big Picture - -![TechDocs Big Picture](../..//assets/techdocs/techdocs_big_picture.png) diff --git a/docs/features/techdocs/architecture.md b/docs/features/techdocs/architecture.md new file mode 100644 index 0000000000..4e063a8559 --- /dev/null +++ b/docs/features/techdocs/architecture.md @@ -0,0 +1,6 @@ +--- +id: architecture +title: Architecture +--- + +![TechDocs Big Picture](../../assets/techdocs/techdocs_big_picture.png) diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index 2fa84cebd6..8f5558c0f8 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -8,9 +8,9 @@ solution in Backstage. ### TechDocs Core Plugin -The TechDocs Core Plugin is a MkDocs plugin created as a wrapper around multiple -MkDocs plugins and Python Markdown extensions to standardize the configuration -of MkDocs used for TechDocs. +The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created +as a wrapper around multiple MkDocs plugins and Python Markdown extensions to +standardize the configuration of MkDocs used for TechDocs. [TechDocs Core](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md) diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index 0dfa40f819..89df2fb18e 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -11,7 +11,7 @@ This section will guide you through: - [Manually add documentation setup to already existing repository](#manually-add-documentation-setup-to-already-existing-repository) - [Writing and previewing your documentation](#writing-and-previewing-your-documentation) -## Prerequisities +## Prerequisites - A working Backstage instance with TechDocs installed (see [TechDocs getting started](getting-started.md)) @@ -81,12 +81,12 @@ updated documentation next time you run Backstage! ## Writing and previewing your documentation Using the `techdocs-cli` you can preview your docs inside a local Backstage -instance and get automatic recompilation on changes. This is useful for when you -want to write your documentation. +instance and get live reload on changes. This is useful when you want to preview +your documentation while writing. To do this you can run: ```bash -cd ~// +cd /path/to/docs-repository/ npx @techdocs/cli serve ``` diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 33edfecbe8..174894b020 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -6,35 +6,8 @@ title: Getting Started TechDocs functions as a plugin to Backstage, so you will need to use Backstage to use TechDocs. -## What is Backstage? - -Backstage is an open platform for building developer portals. It’s based on the -developer portal we’ve been using internally at Spotify for over four years. -[Read more here](https://github.com/spotify/backstage). - -## Prerequisities - -In order to use Backstage and TechDocs, you need to have the following -installed: - -- [Node.js](https://nodejs.org) Active LTS (long term support), currently v12 -- [Yarn](https://yarnpkg.com/getting-started/install) - -## Creating a new Backstage app - -> If you have already created a Backstage application, jump to -> [Installing TechDocs](#installing-techdocs), otherwise complete this step. - -To create a new Backstage application for TechDocs, run the following command: - -```bash -npx @backstage/create-app -``` - -You will then be prompted to enter a name for your application. Once that's -done, a new Backstage application will be created in a new folder. For example, -if you choose the name `hello-world`, a new `hello-world` folder is created -containing your new Backstage application. +If you haven't setup Backstage already, start +[here](../../getting-started/index.md). ## Installing TechDocs @@ -74,7 +47,7 @@ export { plugin as TechDocs } from '@backstage/plugin-techdocs'; ### Setting the configuration TechDocs allows for configuration of the docs storage URL through your -`app-config` file. We provide two different values to be configured, +`app-config.yaml` file. We provide two different values to be configured, `requestUrl` and `storageUrl`. The `requestUrl` is what the reader will request its data from, and `storageUrl` is where the backend can find the stored documentation. @@ -87,13 +60,13 @@ techdocs: requestUrl: http://localhost:7000/techdocs/docs ``` -If you want `techdocs-backend` to manage building and publishing you want +If you want `techdocs-backend` to manage building and publishing, you want `requestUrl` to point to the default value (or wherever `techdocs-backend` is hosted). `storageUrl` should be where your publisher publishes your docs. Using the default `LocalPublish` that is the default value. If you have a setup where you are not using `techdocs-backend` for managing -building and publishing of your documentation you want to change the +building and publishing of your documentation, you want to change the `requestUrl` to point to your storage. In this case `storageUrl` is not required. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 7b4c852f4d..849cd56179 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -62,11 +62,12 @@ }, { "type": "subcategory", - "label": "Docs-like-code", + "label": "TechDocs", "ids": [ "features/techdocs/techdocs-overview", "features/techdocs/getting-started", "features/techdocs/concepts", + "features/techdocs/architecture", "features/techdocs/creating-and-publishing", "features/techdocs/faqs" ] diff --git a/mkdocs.yml b/mkdocs.yml index 10cd7df9b2..c9fa1b7700 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,10 +43,11 @@ nav: - Create your own Templater: 'features/software-templates/extending/create-your-own-templater.md' - Create your own Publisher: 'features/software-templates/extending/create-your-own-publisher.md' - Create your own Preparer: 'features/software-templates/extending/create-your-own-preparer.md' - - Docs-like-code: + - TechDocs: - Overview: 'features/techdocs/README.md' - Getting Started: 'features/techdocs/getting-started.md' - Concepts: 'features/techdocs/concepts.md' + - TechDocs Architecture: 'features/techdocs/architecture.md' - Creating and Publishing Documentation: 'features/techdocs/creating-and-publishing.md' - FAQ: 'features/techdocs/FAQ.md' - Plugins: