You can find the source files for published Cobalt Product Documentation in this repository. It's:
When editing documentation, you should learn how to build the docs "locally" on your system. To set up that build, you need to install:
In addition, the following tools can help you verify ("lint") proposed documentation changes:
aspell
or ispell
markdownlint-cli
Docsy is a Hugo theme for technical documentation sites, providing easy site navigation, structure, and more.
This repository includes the theme as a Git submodule:
▶ git submodule
f82dd5efa0eb5a03086498686f9e60f7bd2bb5f3 themes/docsy (remotes/origin/tekton-example-23-gf82dd5e)
The theme is based on the Docsy Example Project. For detailed theme instructions, see the Docsy user guide: https://docsy.dev/docs/.
To build and run the site locally, you need the following:
A recent extended
version of Hugo. For more information, see the Docsy Getting Started Guide guide.
brew
, the default installation is the extended
version. To confirm, run:hugo version
If you already have Hugo installed, and have just cloned this repository, you'll should then install NPM dependencies.
npm install
After you've made your working copy of the site repository, from its root folder, run:
hugo server -D
You can test links and alt text attributes with htmltest.
Follow the instructions to install htmltest
in the /usr/local/bin folder. The current (1 Nov 2022)
website suggests the following command, which works if you're using the bash
shell:
sudo curl https://htmltest.wjdp.uk | sudo bash -s -- -b /usr/local/bin
If you're using the zsh shell (default in MacOS):
sudo curl https://htmltest.wjdp.uk | sudo zsh -s -- -b /usr/local/bin
Once installed, run the following commands to make sure you've built the latest version of the docs
in the public/
subdirectory:
hugo mod clean
hugo
You can then run the following command in the root directory of this repository.
htmltest
After you fix any bad links, and address accessibility issues, run the commands in this section again.
You'll see error messages similar to:
target does not exist --- platform-deep-dive/pentests/pentest-process/methodologies/api-methodologies/index.html --> ../../special-instructions
In this case, the ../../special-instructions
link does not exist.
alt attribute missing --- integrations/index.html --> /integrations/Jira.png
With images, for accessibility, we need to include "Alt Text". In this case, you might see Markdown code like:
![](/gsg/PentestFlowOverview.png)
To accommodate screen readers, we need "Alt Text" similar to:
![UI Flow for Pentests](/gsg/PentestFlowOverview.png "UI Flow for Pentests")
The .htmltest.yml
includes options to
After you fix broken links, rerun the commands in the Run htmltest section. Otherwise, you'll see the same errors that you "thought" you fixed.
While there are a couple of open issues with the output, related to the link to our Zendesk articles, it does detect other broken links.
Non-OK status: 403 --- index.html --> https://cobaltio.zendesk.com/hc/en-us/categories/360005476672-Cobalt-Platform
Non-OK status: 403 --- index.html --> https://cobaltio.zendesk.com/hc/en-us/categories/360005476672-Cobalt-Platform
For more information, see GrammarLinter.md
Includes custom settings in layouts/partials/head.html for <title>
and <meta>
tags. Based in part on https://harrycresswell.com/writing/hugo-seo-accurate-page-titles/.
As you run the website locally, you may run into the following errors:
➜ hugo server
INFO 2021/01/21 21:07:55 Using config file:
Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
Built in 288 ms
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
This error occurs for one of the following reasons:
postcss-cli
NPM package.If you run into a format error, where punctuation seems to have extra space after links, you may want to reconfigure your IDE. For example, if you use vim, you can add the following lines to your vim configuration file (~/.vimrc):
set noendofline
set nofixendofline
Internal Cobalt #docs channel or ana-dashuk-cobalt.
SOC2 is not a requirement, as this repository does not host customer-exposed production workloads. However, the SOC2 conventions are a good practice. This repository deviates from SOC2 conventions in the following ways for the noted reasons: