TechDocs
The TechDocs plugin allows your engineers to write their documentation in markdown files which live together with their code and display them in kobs.
Configuration
To use the TechDocs plugin the following configuration is needed in the satellites configuration file:
Field | Type | Description | Required |
---|---|---|---|
name | string | The name of the TechDocs plugin instance. | Yes |
type | techdocs |
The type for the TechDocs plugin. | Yes |
options.provider.type | string | The provider type. Must be local or s3 |
Yes |
options.provider.local.rootDirectory | string | The path to the directory, which contains all the folders with your TechDocs for your services. | Yes |
options.provider.s3.endpoint | string | The endpoint for your S3 bucket. | Yes |
options.provider.s3.accessKeyID | string | The access key id for your S3 bucket. | Yes |
options.provider.s3.secretAccessKey | string | The secret access key for your S3 bucket. | Yes |
options.provider.s3.bucket | string | The name of the S3 bucket with your TechDocs. | Yes |
options.provider.s3.useSSL | boolean | Use SSL to access the S3 bucket. | Yes |
plugins:
- name: techdocs
type: techdocs
options:
provider:
type: local
local:
rootDirectory:
# type: s3
# s3:
# endpoint:
# accessKeyID:
# secretAccessKey:
# bucket:
# useSSL: true
Insight Options
Note
The TechDocs plugin can not be used within the insights section of an application.
Variable Options
Note
The TechDocs plugin can not be used to get a list of variable values.
Panel Options
The following options can be used for a panel with the TechDocs plugin:
Field | Type | Description | Required |
---|---|---|---|
type | string | Specify if you want to show a list of TechDocs or the table of contents (toc ) for a specific service. |
Yes |
service | string | The name of the service for which the table of contents should be shown when the type is toc . |
No |
Notification Options
Note
The TechDocs plugin can not be used to get a list of notifications.
Usage
The TechDocs plugin renders the markdown files for your service. For that you have to provide the files for kobs via S3 or via a file system which kobs can access.
File Structure
The TechDocs for all of your service must live in their own folder. Lets say we have four services productpage
, details
, ratings
and reviews
. All of these services have their own documentation, so that the final structure for kobs should look as follows:
techdocs
├── details
│ └── index.yaml
├── productpage
│ ├── configuration
│ │ ├── addbooks.md
│ │ └── getting-started.md
│ ├── index.md
│ ├── index.yaml
│ └── installation
│ ├── helm.md
│ └── kustomize.md
├── ratings
│ └── index.yaml
└── reviews
└── index.yaml
As you can see each folder must also contain a index.yaml
file with the following content:
# The key should be a unique identifier for all of your TechDocs.
# It must have the same name as the folder, where the TechDocs for the service are stored for kobs.
key: productpage
# The name of your service and a short description of your service.
name: Productpage
description: The productpage for the bookinfo application.
# The first markdown file which should be shown, when a user opens the TechDocs for the service.
home: index.md
# The table of contents for your service, with links to all the markdown files should can be accessed by a user.
toc:
- Home: index.md
- Installation:
- Helm: installation/helm.md
- Kustomize: installation/kustomize.md
- Configuration:
- Getting Started: configuration/getting-started.md
- Add Books: configuration/addbooks.md