The TechDocs plugin allows your engineers to write their documentation in markdown files which live together with their code and display them in kobs.
To use the TechDocs plugin the following configuration is needed in the satellites configuration file:
|name||string||The name of the TechDocs plugin instance.||Yes|
||The type for the TechDocs plugin.||Yes|
|options.provider.type||string||The provider type. Must be
|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
The TechDocs plugin can not be used within the insights section of an application.
The TechDocs plugin can not be used to get a list of variable values.
The following options can be used for a panel with the TechDocs plugin:
|type||string||Specify if you want to show a
|service||string||The name of the service for which the table of contents should be shown when the type is
The TechDocs plugin can not be used to get a list of notifications.
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.
The TechDocs for all of your service must live in their own folder. Lets say we have four services
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