@qery/docs NPM

Query Docs

A lightning-fast, feature-rich markdown documentation generator. Transform your markdown files into beautiful, navigable documentation websites.

Features

Effortless Documentation - Convert markdown files to HTML with a single command
Smart Navigation - Automatically generates previous/next links between pages
Hierarchical TOC - Creates a structured table of contents from your SUMMARY.md
Full-Text Search - Built-in search functionality with JSON index
Customizable Templates - Use your own HTML templates for full control over styling
Fast & Lightweight - Built in Rust for exceptional performance

Installation

For JavaScript

pnpm add @qery/docs

npm install @qery/docs

From Source

git clone https://github.com/gc-victor/query.git
cargo build --package query-docs --release

The compiled binary will be available in ./target/release/query-docs.

Quick Start

Create a directory for your documentation:

mkdir docs
cd docs

Create a SUMMARY.md file that defines your documentation structure:

# Summary

## Getting Started

- [Introduction](introduction.md) Description of the introduction
- [Installation](installation.md) Description of the installation process

## User Guide

- [Basic Usage](usage/basic.md) Description of basic usage
- [Advanced Features](usage/advanced.md) Description of advanced features

Create the corresponding markdown files mentioned in your SUMMARY.md
Create a template.html file in the same directory or specify a custom one
Generate your documentation:

query-docs --input ./docs --output ./build

Your documentation is now ready in the ./build directory!

Usage

Command Line Options

USAGE:
    query-docs [OPTIONS] --input <INPUT_DIR> --output <OUTPUT_DIR>

OPTIONS:
    -i, --input <INPUT_DIR>           Directory containing markdown files
    -o, --output <OUTPUT_DIR>         Directory to output HTML files
    -t, --template <TEMPLATE_FILE>    HTML template file to use by default INPUT_DIR/template.html
        --no-search                   Disable search functionality
    -h, --help                        Print help information
    -V, --version                     Print version information

SUMMARY.md Format

The SUMMARY.md file defines the structure of your documentation. It follows a simple format:

# Summary

## Section 1

- [Page Title](path/to/page.md)
  - [Nested Page](path/to/nested.md)

## Section 2

- [Another Page](another-page.md)

Use ## headings to create sections in your table of contents
Use bullet points (-) followed by Markdown links to define pages
Indented bullet points create nested pages in the hierarchy

Template Customization

@qery/docs uses the MiniJinja template engine. Your template has access to the following variables:

title: The title of the current page
description: The description of the current page
content: The HTML content of the current page
navigation: Navigation object with:
- previous: Previous page (title and URL) or null
- next: Next page (title and URL) or null
- current: Current page (title and URL)
toc: Table of contents object
search_enabled: Boolean indicating if search is enabled

For more information about MiniJinja syntax, see the documentation.

Example Template

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title }}</title>
    <meta name="description" content="{{ description }}">
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <nav class="toc">
        <h1>Table of Contents</h1>
        {% for group in toc.items %}
            <h2>{{ group.name }}</h2>
            <ul>
            {% for item in group.items %}
                <li><a href="{{ item.url }}">{{ item.title }}</a></li>
            {% endfor %}
            </ul>
        {% endfor %}
    </nav>

    <main>
        <article>
            {{ content }}
        </article>
    </main>

    <nav class="pagination">
        {% if navigation.previous %}
            <a href="{{ navigation.previous.url }}" class="prev">← {{ navigation.previous.title }}</a>
        {% endif %}
        
        {% if navigation.next %}
            <a href="{{ navigation.next.url }}" class="next">{{ navigation.next.title }} →</a>
        {% endif %}
    </nav>

    {% if search_enabled %}
    <script src="search.js"></script>
    {% endif %}
</body>
</html>

Examples

Basic Documentation Site

# Project structure
docs/
├── SUMMARY.md
├── template.html
├── introduction.md
├── getting-started.md
└── api-reference.md

# Generate documentation
query-docs --input ./docs --output ./site

Multi-section Documentation

# Summary

## Introduction
- [Overview](index.md)
- [Getting Started](getting-started.md)

## API Reference
- [Authentication](api/auth.md)
- [Endpoints](api/endpoints.md)
  - [Users API](api/endpoints/users.md)
  - [Products API](api/endpoints/products.md)

## Tutorials
- [Quick Start](tutorials/quickstart.md)
- [Advanced Usage](tutorials/advanced.md)

Using Custom Template

# Generate with custom root template
query-docs --input ./docs --output ./site --template ./custom-template.html

Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Please make sure your code passes all tests and follows the project's coding style.

Testing

@qery/docs uses Rust's built-in testing framework. Run the tests with:

cargo test

The test suite includes unit tests and integration tests to ensure all features work correctly.

License

This project is licensed under the MIT License - see the LICENSE file for details.

FAQ

How is @qery/docs different from mdBook?

While mdBook is a fantastic tool, @qery/docs focuses on providing a simpler, more lightweight solution with enhanced navigation and customizable templates. It's designed to be easy to use while still offering powerful features like hierarchical TOC and built-in search.

Can I use custom CSS with @qery/docs?

Yes! You can include any CSS in your HTML template. Additionally, you can reference external CSS files that you can place in your output directory.

Does @qery/docs support syntax highlighting?

Yes, code blocks in your markdown are properly preserved and can be syntax-highlighted using any JavaScript library of your choice (like Prism.js or highlight.js) by including it in your template.

Can I deploy the generated site to GitHub Pages?

Absolutely! The generated HTML is static and can be deployed to any static site hosting service like GitHub Pages, Netlify, or Vercel.

axios axios-proxy-builder console.table detect-libc rimraf

0.12.49

8 months ago