vitepressify

Convert Crystal docs into VitePress

What is vitepressify?

Crystal docs are awesome, but sometimes you need more control over them.

vitepressify generates a VitePress project with paegs from your local or remote Crystal docs.

• It automatically generates markdown pages and sidebars.
• It provides a table of contents.
• It can update an already made project with more versions or other shards.
• It automatically handles loading sidebars and cases where navabar has 1 vs more items, without the need to overwrite any configs.
• It comes with a purple accent.

Installation

Pre-built

You can download one of the statically-linked pre-built binaries from the releases page.

They are built & published by our lovely actions.

Building

Dependencies

• crystal - 1.5.0

Manually

$ shards build --production --no-debug --release

Usage

Vitepressify v1.0.0
Usage:
    vitepressify [arguments]
Examples:
    vitepressify -i ./docs/index.json
    vitepressify -i https://crystal-lang.org/api/1.5.0/ -t 1.5.0
    vitepressify -i https://geopjr.github.io/gettext.cr/index.json -u ./vitepressify-docs

Arguments:
    -i INDEX, --index=INDEX          index.json location. Can be either a local path or a url (e.g. https://libadwaita.geopjr.dev/docs/). Default: ./docs/index.json
    -t TAG, --tag=TAG                Current release/tag (e.g. 1.0.0). Default: main
    -u FOLDER, --update=FOLDER       Instead of generating a new project, it attempts to update the one at FOLDER.
    -l, --license                    Show the LICENSE
    -h, --help                       Show this help

Example

If you wanted for example to build a VitePress project using the Crystal API docs from 1.4.0 to 1.5.1, all you have to do is:

• Generate the initial project, using the link to the 1.5.1 docs with the tag of 1.5.1.

$ vitepressify -i https://crystal-lang.org/api/1.5.1/ -t 1.5.1

This will generate the project in a random named folder, for example vitepress-ujqywe.

• Now we just tell vitepressify to update that folder with the other versions:

$ vitepressify -i https://crystal-lang.org/api/1.5.0/ -t 1.5.0 -u ./vitepress-ujqywe/

$ vitepressify -i https://crystal-lang.org/api/1.4.1/ -t 1.4.1 -u ./vitepress-ujqywe/

$ vitepressify -i https://crystal-lang.org/api/1.4.0/ -t 1.4.0 -u ./vitepress-ujqywe/

• And we are done!

Contributing

1. Read the Code of Conduct
2. Fork it (https://github.com/GeopJr/vitepressify/fork)
3. Create your feature branch (git checkout -b my-new-feature)
4. Commit your changes (git commit -am 'Add some feature')
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request

Sponsors