The official docs site for Covalent. This is also referred to as the Knowledge Base.
The directions on how to showcase your project is here.
Please read the contribution guidelines here.
Covalent uses the Cloudflare documentation engine for the docs site.
-
Install the
hugo
server for your machine: https://gohugo.io/getting-started/installing/ -
Checkout this repo
-
Install the dependencies with:
npm install
. If you run into an error due to legacy dependencies, install using the flag:npm install --legacy-peer-deps
-
Install the Cloudflare documentation engine with:
npm run docs-bootstrap
. If you run into an error due to legacy dependencies, run using the flag:npm run docs-bootstrap --legacy-peer-deps
Note: You may get an error message suggesting you to install
gatsby
. You do not need to do this. -
Build the docs site with:
./s/docs-build
-
Create an empty
config.yaml
in your project root folder. This is required in order to run thehugo
server. -
Run the
hugo
server which should render the contents frompublic/
. If this does not happen by default, directhugo
to thepublic
folder with the following:hugo server --contentDir ./public
For a comprehensive overview of how the Cloudflare docs engine works, see this excellent resource.
The content is generated as static HTML pages in public/
and then rendered.
For a comprehensive overview on creating content using the Cloudflare docs engine, see this excellent resource
Some helpful things to know about creating content pages:
-
Content for the docs site is added in
docs/content/
. You must have at least anindex.md
inside this folder. -
The sidebar navigation tree and page paths are automatically generated from the file structure and naming in
docs/content/
- Each page starts with a frontmatter which outlies the metadata for the page and looks something like:
--- title: Tutorials hidden: false order: 1 ---
-
Note the frontmatter's used for tutorials, case studies and other detailed content (see below) is generally more involved.
-
The
title
value is what is used in the sidebar navigation tree. If atitle
is not specified, the firsth1
in the Markdown is used.
-
index.md
files inside sub-folders ofdocs/content/
will take the pathname of their parent directory (e.g. navigation tree menu label for content innetworks/index.md
shows up undernetworks
). -
You can include custom MDX components in
docs/components/
as.js
files and import them into.md
files. See the Topic Calculator markdown for an example. -
For using images, create a local
images/
folder inside your content sub-folder and import them accordingly. -
There is a built-in MDX components for embedding YouTube clips where you simply just need to use the clip ID like this example:
<YouTube id="qhibXxKANWE"/>
Use this template when creating any new learning series content such as a Tutorial, How-to Guide or Case Study. Please follow these fontmatter guidelines:
-
type
: Use eitherArticle
orVideo
orCode
if it's entirely an embedded code template. -
featuredImage
: Create a content banner using the Covalent Figma templates. Ask a Covalent admin for this info. -
tags
: Keep these high-level and reusable so that they can effectively filter content but not so specific that they only apply to a single article.
Each learning series content should be treated as a 'stand-alone' page.
Everytime you commit to a branch, we deploy a fully built website for preview. Check the comments on your pull request for the live URL.
We use two different packages to build our documentation:
-
The Covalent API reference automatically generated from the backend's OpenAPI specification.
-
The high-level Knowledge Base which includes tutorials, how-to guides and case studies.
All of the Covalent API interactive features are built using Java's @OpenAPI
annotations.