Disenchanted

moon
sun

Introducing Vite Book

February 04, 2022

Motivation

In the past few years, I tried lots of documentation generators, such as docsify, docusaurus, docz, etc… But I couldn’t find a good one that I liked for following reasons:

  1. I have to switch between my markdown editor and the browser many times during writing docs to make sure they looks good. Which is really annoying when I only have one screen with me.
  2. Sometimes I don’t want to do so much configuration to just create a documentation site. For example, when creating a library. I just want my documentation site to be simple to setup and easy to write.
  3. Markdown based documentation may block people that don’t know how to use markdown. It’s not common in programmers, but what about designers and PM? If they also want to contribute to the docs, they have to learn it first.

Introducing Vite Book

So I created a new way to write and manage your documentation. It’s called Vite Book. It’s built on top of the vite ecosystem. So you can use it as a vite plugin in your project.

Quick Start

Init a project using vite and add the vite-plugin-book package as the dependency:

npm init vite@latest my-vite-book -- --template vanilla

cd my-vite-book

npm install --save vite-plugin-book

Then, open the vite.config.js and add the plugin:

// vite.config.js
import { book } from 'vite-plugin-book/vite';

export default {
    plugins: [book()],
};

After that, you can just run npm run dev, and you’ll see the following message in terminal:

vite dev server running at:

> Local: http://localhost:3000/
> Network: use `--host` to expose

ready in XXXms.

> Book Admin: http://localhost:3000/__vite_plugin_book__/
> Book Preview: http://localhost:3000/__vite_plugin_book__/__preview__/

Now you can view the book admin to play with your book!

Overview

Create a new page:

new page

Create a new menu:

new menu

Drag and drop to sort:

dnd

Delete items:

delete

More User Interfaces:

ux

Deployment

You can also make your book available to the public.

Add following code to your main.js:

// Don't forget to import css!
import 'vite-plugin-book/style.css';

import { renderBook } from 'vite-plugin-book';

renderBook({
    isProd: import.meta.env.PROD,
    baseUrl: import.meta.env.BASE_URL,
    container: '#app',
});

Then, you can observe the book in production with:

npm run dev
npm run preview

In production, the book will be readonly. Editing the book is only possible in development mode.

Online playground

You can play with it on stackblitz.

Summary

For now, you’ve already get a book which you can:

  1. Write and manage documents just in browser.
  2. Ready for deployment.
  3. Have mobile support, sidebar, dark mode, loading status, share, etc… out of the box.

What’s next?

I’ll continue work on this library to make it support more features. The following features are planned:

  • plugin system
  • theme system
  • configurable editor
  • i18n

Support Me

If you like this idea, please consider to give it a 🌟 on GitHub.


Mirone

Personal blog by Mirone. Kiss the demons out of my dreams.