Docsi Docs

Welcome to the Docsi Docs! 🎉🎉🎉

What is Docsi?

Installation

Install the CLI globally:

npm install -g @docsi/cli

Then run the following command :

docsi new my-docs

After a few questions, the CLI will generate a new Docsi project in the my-docs folder.

Environment

Development

  1. Install the grunt CLI. 
npm install -g grunt-cli
  1. Start the development server. 
npm run dev

The development server will be started on http://127.0.0.1:5173/temp/index.html.

Note: The development server is only for development purposes.

Build

To build the static site, you can run npm run build in the root folder.
The static site will be generated in the dist folder.

Folder Structure

- node_modules/
- src/
    - assets/
        - logo.png
    - content/
        - Environment.md
        - Examples.md
        - Introduction.md
    - css/
        - default.css
        - highlight.css
        - sidebar.css
    - js/
        - sidebar.js
    - template.html
- .gitignore
- docsi.config.js
- package.json
- package-lock.json
- README.md
- vite.config.js

Important: Please make sure if you create a new file in content/ then you have to register it to the docsi.config.js file.

Configuration

As you can see, there is a docsi.config.js file in the root folder. 

const docsiConfig = {
    // Order how pages are merged together
    pageOrder: [
        "Introduction",
        "Environment",
        "Examples"
    ],
    build: {
        minifyJs: true,
        minifyCss: true,
        buildDir: "dist"
    },
    fileLocations: {
        template: "src/template.html"
    },
    folderLocations: {
        assets: "src/assets",
        pages: "src/content",
        css: "src/css",
        js: "src/js"
    },
    // Custom markdown compiler options
    markdown: {
        preCompile: (md) => {
            // checkbox - <input type="checkbox" disabled> || - <input type="checkbox" checked disabled>
            md = md.replace(/- \[ ]/g, '- <input type="checkbox" disabled>');
            md = md.replace(/- \[x]/g, '- <input type="checkbox" checked disabled>');
            // mark special words <mark>word</mark>
            md = md.replace(/<mark>(.+?)</mark>/g, '<mark>$1</mark>');
            // sup numbers <sup>2</sup> to <sup>2</sup>
            md = md.replace(/\^(\d+)\^/g, '<sup>$1</sup>');
            return md;
        },
        postCompile: (html) => {
            return html;
        }
    }
}
module.exports = docsiConfig;

Examples

Styling

You can write normal HTML in the Markdown files.
So you can easily assign classes to elements.

My paragraph

<div class="my-class">
    <p>My paragraph</p>
</div>

Now you can create a new CSS file in the css folder and add the following code:

.my-class {
    background-color: red;
}

The css file gets automatically imported in the template.html file, if it's in the css folder.

Code Highlighting

You can use code highlighting in the Markdown files.
Just use the following syntax:

console.log("Hello World!");

```js
console.log("Hello World!");
```

If you want to change the code highlighting theme, you can change it in the highlight.css file.

If you want to remove the highlighting, you can delete the highlight.css file and remove the following line in the template.html file:

<!-- Highlight.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>

Images

You can use images in the Markdown files.
Just use the following syntax:

Logo

![Logo](assets/logo.png)

or

<img src="assets/logo.png" alt="Logo" />

If you want to change the logo or add a new one, you can change it in the assets folder.

Adding new pages

If you want to add a new page, you can create a new Markdown file in your content folder.
Then you have to register it in the docsi.config.js file. 

pageOrder: [
  "Introduction", 
  "Environment", 
  "Examples", 
  "NewPage"
]
...

Please note that docsi only creates single page applications.
So all theses pages will be rendered in the same HTML file. You can just define the order of the pages.

Adding Scripts

If you want to add a new script, you can create a new JS file in the js folder.
You don't have to register it anywhere, it gets automatically imported in the template.html file, if you put it in the js folder. 

<button onclick="alertHelloWord()">Add a new script!</button>

now you can create a new JS file in the js folder and add the following code:

function alertHelloWord() {
    window.alert("Hello World!");
}

template.html

The template.html file is the template file for the static site.
It contains the HTML structure of the static site.
You can add your own HTML code to it.

There you can change the title of the static site.