This repository holds the documentation for the kabanero-io site Docs area. These docs are dynamically pulled in during the Kabanero-website build process.
- Click the
forkbutton to create your fork of thedocsrepo. Make changes on your fork then open a pull request againstkabanero-io/docs:masterwhen you're ready for the changes to be reviewed and merged.
You have 2 options when creating docs: Markdown and AsciiDoc.
- We use Jekyll, which uses the kramdown Markdown renderer, which still supports standard Markdown with some minor modifications.
- We use the Jekyll-asciidoc plugin, which uses Asciidoctor to render AsciiDocs
You need the proper front matter on each Docs page to get it categorized correctly. The title and the doc-category are the only one you should change.
- For Markdown, use a YAML front matter
--- layout: doc doc-category: Reference title: Connecting Kabanero to GitHub with Tekton Webhooks --- - For AsciiDoc, use
page-AsciiDoc attributes in place.:page-layout: general-reference :page-doc-category: Configuration :page-title: Connecting Kabanero to GitHub with Tekton Webhooks :linkattrs: :sectanchors:
We currently have 4 categories you can use for the doc-category (markdown) or :page-doc-category: (AsciiDoc) front matter:
- Overview
- Installation
- Configuration
- Reference
If you need a new category feel free to open an issue or discussion in a pull request about the new category.
The doc-categories.adoc file configures the order that the doc categories will show up on our table of contents for the website. Currently the order is:
- Installation
- Configuration
- Reference
This file should only be updated if a new category is added.
- If a new category is added you must place your category in the
page-categoriesin the order you want it to show up on the site.
Defines the order in which the docs are displayed in a given category.
For example :page-doc-number: 1.0 in the Configuration category will be listed in the doc dropdown menu before :page-doc-number: 2.0 in the Configuration category.
Note: If you want to insert a new doc between two other docs use a numerical value between the two :page-doc-number values. For example, if you want to add a doc between the current #1 and #2 docs you can do: :page-doc-number: 1.1.
Create a Markdown/AsciiDoc file that contains the documentation in a presentable format. For help on syntax you can view these references:
- Syntax references
- Editor options
If you want to get a Docs page ready ahead of time, but do not want it published to the site you can still contribute the file, but be sure to include the published: false front matter. When you are ready for the Docs page to be published, you can remove the published front matter variable:
- For Markdown use
published: false - For AsciiDoc use
:page-published: false
To add an image to your Docs page, put the image in the img/ directory. You can reference this image in your Docs page by using the path to the img/ directory. For example, if you added my_image.png to the img/ directory you can use that image with the following syntax:
- AsciiDoc format:
image::/docs/img/my_image.png[My image alt text]. - Markdown format:
Note: The image will not show for the GitHub preview, but it will be linked on the website when it's deployed.
In this repository you should place your new Docs page under the folder that best describes the documentation category. These folders are located in the ref directory
Follow these instructions to render your docs in the website on a local dev environment.
- From the kabanero-website repository root run the script:
./scripts/build_clone_docs.sh - Create your new
.adocor.mdfile insrc/main/content/docs/ref/general/and write in your doc content. - Copy any images that you are using in your doc to the
src/main/content/docs/img/directory. - Start your local dev server using instructions from the local dev setup and go to https://localhost:4000/docs in your browser to see all the Docs pages rendered.