Covalent Docs

The official docs site for Covalent. This is also referred to as the Knowledge Base.

Project Showcase

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 the hugo server.
Run the hugo server which should render the contents from public/. If this does not happen by default, direct hugo to the public 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 an index.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 a title is not specified, the first h1 in the Markdown is used.
index.md files inside sub-folders of docs/content/ will take the pathname of their parent directory (e.g. navigation tree menu label for content in networks/index.md shows up under networks).
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 either Article or Video or Code 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.