LvffYid, title, sidebar_label, description
| id | title | sidebar_label | description |
|---|---|---|---|
| techdocs-overview | TechDocs Documentation | Overview | TechDocs is Spotify’s homegrown docs-like-code solution built directly into Backstage |
What is it?
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. 🎉
Features
- Deploy TechDocs no matter how your software environment is set up.
- Discover your Service's technical documentation from the Service's page in Backstage Catalog.
- Create documentation-only sites for any purpose by just writing Markdown.
- Explore and take advantage of the large ecosystem of MkDocs plugins to create a rich reading experience.
- Search for and find docs.
- Highlight text and raise an Issue to create feedback loop to drive quality documentation (future).
- Contribute to and deploy from a marketplace of TechDocs widgets (future).
Platforms supported
See TechDocs Architecture to get an overview of where these providers are used.
| Source Code Hosting Provider | Support Status |
|---|---|
| GitHub | Yes ✅ |
| GitHub Enterprise | Yes ✅ |
| Bitbucket | Yes ✅ |
| Azure DevOps | Yes ✅ |
| GitLab | Yes ✅ |
| GitLab Enterprise | Yes ✅ |
| File Storage Provider | Support Status |
|---|---|
| Local Filesystem of Backstage app | Yes ✅ |
| Google Cloud Storage (GCS) | Yes ✅ |
| Amazon Web Services (AWS) S3 | Yes ✅ |
| Azure Blob Storage | Yes ✅ |
| OpenStack Swift | Community ✅ |
Reach out to us if you want to request more platforms.
Project roadmap
Published versions
Alpha release ✅ - Milestone
- Alpha of TechDocs that you can use end to end - and contribute to.
Beta release ✅ - Milestone
- TechDocs' recommended setup supports most environments (CI systems, cloud storage solutions, source control systems).
- Instructions for upgrading from Alpha to Beta
v1 ✅
TechDocs packages:
- '@backstage/plugin-techdocs'
- '@backstage/plugin-techdocs-backend'
- '@backstage/plugin-techdocs-node'
- '@techdocs/cli'
was promoted to v1.0! To understand how this change affects the package, please check out our versioning policy.
Future work 🔮
- Better integration with Scaffolder V2 (e.g. easy to choose and plug documentation template with Software Templates).
- Static site generator agnostic
- Possible to configure several aspects about TechDocs (e.g. URL, homepage, theme).
- TechDocs Addon Framework
Tech stack
| Stack | Location |
|---|---|
| Frontend Plugin | @backstage/plugin-techdocs |
| Backend Plugin | @backstage/plugin-techdocs-backend |
| CLI (for local development and generating docs) | @techdocs/cli |
| Docker Container (for generating docs) | techdocs-container |
Contact us
Reach out to us in the #docs-like-code channel of our
Discord chatroom.