Chul or Chull is an informal Hindi word, which merely means Itching. This module is the result of itching I had to create dead simple and time efficient static documentation generator for myself.
Instead of building themes through their build process. Chul encourages you to use the parts of theme and build them into your build process.
|
Note
|
Do note the keyword documentation here. Chul is not a static site generator like Jekyll or Hugo, it is a static generator but only for documentation.
|
Before you spend time in ready this document, lemme put some points that will help you in deciding on using Chul or not.
-
✓ Uses asciidoc over markdown. Markdown is not the right tool
-
✓ There is no way to mold this module. It is for documentation and will be for documentation.
-
✓ You decide the layout and the appearance.
-
✓ Doesn’t build CSS or any other assets for you. PostCSS build
-
✓ Deploy output to Github docs or Netlify directly.
-
✓ Used by AdonisJs and friends and if your docs are similar to it, then you will save lots of time.
-
✓ Heavily relies on Tailwind CSS
-
✓ Uses Edge template engine
The themes in Chul are not giant themes that come with everything. Trust me, No one ever want to build sites, which uses layouts of others.
We all want personal touch on our websites, and no one can decide, where to put the logo and how to design the header.
-
Chul themes have no build process. Instead, they rely on your build process to import and use them.
-
Chul themes do not have any layouts.
-
They come with 2 Edge partials and one CSS style ( for typography only ).
Since I wanted themes to be super small, they have to be of some value. Every theme comes with a class file, and this file has almost near to perfect typography for the docs.
|
Note
|
The CSS file relies on Tailwind Css and must be compiled via PostCSS and Tailwind CSS only.
|
Why Tailwind?
There is no point if the docs typography is not in sync with your website styles, whether it is the font-color or the line-height, everything has to be same.
Tailwind CSS makes it easier for me to use its configuration without adding it to the theme. Read Build CSS using Webpack to learn more.
Since Chul themes rely on Tailwind, they have to rely on PostCSS as well ( Tailwind is a PostCSS plugin ). With following inside postcss.config.js file, it should work great for you.
const tailwindcss = require('tailwindcss')
const atImport = require('postcss-import')
const chul = require('chul')
const path = require('path')
module.exports = {
plugins: [
atImport({
addModulesDirectories: [path.join(__dirname, 'themes', chul.theme)]
})
tailwindcss(path.join(__dirname, 'tailwind.js'))
]
}We are using postcss-import plugin to import the css file from your current theme
@import "theme-style";
@tailwind preflight;
@tailwind utilities;The theme-style is the css file shipped with each theme.
The reason we do not make use of Markdown is that it is not the right tool for the Job.
Markdown is a simple markup language and extreme limitations, due to which people create Markdown flavors so that they can missing functionality to it.
On the other hand, AsciiDoc is written to write docs. Read more here http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent