Getting Started

Installation

Prerequsiite

• Python version >= 3.9
• Basic Markdown knowledge
• Terminal for accessing Vai via its command line interface (CLI).
• Text Editor with Markdown syntax support. VSCode is recommended.

Install

Run the command below. It is strongly recommended to run this in a venv. It is still ok to run it globally.

pip install vai-ssg

Usage

There are only 3 commands to know. and they are:

• vai init
• vai run
• vai build (only used for deploying your website. Look at the Deploy section)

vai init

It is strongly recommended to run the project in a venv

vai init

This is the first command you should run in your project. Before running vai init, make sure you are in a directory where u will generate your static sites as vai init will populate the current directory. Upon running the command, you will a file strucutre generated. Look below for more info.

vai run

vai run

You can now run vai run in your terminal and it will start the development server at localhost:6600. By default you will see a Welcome to vai page generated by vai init. You will start to see live changes as you create, delete and modify your markdown files. Before you can start typing however, it is important to understand the number-Name folder and file structure vai uses. Continue reading this tutorial to understand how to use vai.

File Structure

After running vai init, you will notice the following structure being generated in your current directory:

.
├── config.yaml
├── src_html
├── src_md
│   ├── 1-Welcome
│   │   └── 1-welcome.md
│   └── README.md
├── static
│   ├── favicon.png
│   ├── logo.png
│   ├── script.js
│   └── style.css
└── templates
    └── layout_no_header.html

There is a lot files and directories here, but the most of the times, you would just be interacting with the src_md/ directory where u will write all the markdown files and it's logic. In this Getting started section, we wil only go through the config.yaml, favicon.png, logo.png and src_md/. If you are content with the default settings, you can ignore the rest of the files, else you can look them up in the Further Customisation section.

Source code

You have to write content in src_md directory. Vai uses directory and file names to build the site structure and sidebar

• Uses a number-Name pattern for ordering in the sidebar.
• directories = sidebar section.
• Markdown files = pages.
• The numbering is important to show how it is ranked in the left sidebar

Example:

src_md/
├── 1-Introduction/
│   ├── 1-What is Vai.md
│   └── 2-Getting Started.md
└── 2-Advanced/
    └── 1-Advanced Features.md

Resulting URLs:

• /introduction/what-is-vai/
• /introduction/getting-started/
• /advanced-features/search/

Images

You must add your images inside of the static directory. When linking, you should link it via /static/<file-name>. For better organisation, it is encouraged to create a seperate directory (e.g. images) inside of the static directory to store your images and link them appropriately(e.g. /static/images/<file-name>).

If you would like to add your own custom logo (located at the top left, above the sidebar) and favicon, replace the default favicon.png and logo.png with your own custom one. Do note that the extension does not matter as long as it is a viable image. It just so happens that the default images for vai are in .png format.

You can ignore the script.js and style.css files if you are content with the styling and logic of the site. Look at Advanced Section for further customisation.

For linking images, you must add the image inside of the static directory.

Config File (config.yaml)

The config.yaml file is responsible for seeting your site's header, navigation, and other global links. Below is the default config.yaml file you will see after running vai init

github_link: "https://github.com/Nareshix/vai"
edit_this_page_on_github_link: 'https://github.com/Nareshix/vai/tree/main/docs/src_md'
github_repo_name: "vai" # CASE SENSITIVE

internals:
  - title: "Placeholder"
    link: "#"


externals:
  - title: "Documentation"
    link: "https://vai-docs.pages.dev/"


dropdowns:
  - main_title: "Menu"
    items:
      - title: "Placeholder"
        type: internal
        link: "#"

      - title: "Documentation"
        type: external
        link: "https://vai-docs.pages.dev/"

Lets discuss more about the key value pairs below

Header Navigation Links

These settings control the links that appear in the top navigation bar of your site.

1. internals

They will open in the same browser tab.

internals:
  - title: "Introduction"
    link: "/introduction/"

2. externals

They will open in a new browser tab and display an "external link" icon.

externals:
  - title: "Further Customisation"
    link: "/further-customisation/"

3. dropdowns

Use this to group multiple links under a single menu item. Each item in the dropdown can be specified as internal or external.

dropdowns:
  - main_title: "Menu"
    items:
      - title: "example.com"
        type: "external"
        link: "https://example.com/"

      - title: "Further Customisation"
        type: "internal"
        link: "/further-customisation"

GitHub Integration

These settings connect your documentation site to its source repository on GitHub.

1. github_link

Controls the GitHub logo icon in the top-right corner of the header. Set this to your repository’s main URL. Leave it blank to hide the icon.

```yaml
github_link: "YOUR_GITHUB_LINK"
```

2. edit_this_page_on_github_link

Controls the “Edit this page on GitHub” link at the bottom of each page. This lets readers suggest improvements.

```yaml
edit_this_page_on_github_link: "YOUR_GITHUB_CONRIBUTION_PAGE"
```

3. github_repo_name

• This is essential only if you are deploying to GitHub Pages.
• Keep in mind that the repo name is Case sensitive

github_repo_name: "vai"

What's Next?

Before you starting using vai, it is important to check out the final section of the Inroduction which is Markdown Syntax. It does not teach you about Makrdown Syntax but rather explore common things that are slightly different in vai.