# Doctopus

<img src="../icon.webp" width="128" height="128" alt="Doctopus logo" style="float: right; margin: 0 0 1em 1em; border-radius: 50%;" />

The simplest way to write beautiful documentation.

Write Markdown files in your `docs` directory. Run `doctopus` to generate a static site. Done.

You get a static HTML site that is easy to read for both humans and AI.

If you need a more complex homepage, you can write it in React instead of Markdown.
Just create an `index.tsx` file in the `docs` directory and export an `App` component.

## Why?

I used Astro Starlight for a while and it works but was not the right fit for my needs.

The documentation software I've tried so far offered features I didn't want and lacked some I did.
They offered customization in places I didn't care about, but lacked the customization I needed.
And they were way too slow.

My philosophy is to write software that respects me and my users.

I wanted full static builds, no server, no client-side JavaScript for rendering static diagrams/math, image optimization by default, machine-readable pages for AI agents.
I wanted a fully custom and interactive homepage, with the rest of the documentation as boring Markdown.

Finally, a reasonable build time was essential
This documentation builds in under 40 ms on my laptop.
This is usually less than the time Node.js takes to start up, before it can start to do actual work.

I made this program for my needs.
If my needs align with yours, feel free to use it.

If you you want parts of it, it is built in a way to be consumable as a library.
As a library it offers more flexibility than I surfaced in the CLI.
The CLI auto-discovers everything and is made for easy use.
The library is more explicit and offers more control.

## Installation

#### Pre-compiled

```bash
curl --proto '=https' --tlsv1.3 -sSf https://doctopus.pages.dev/install.sh | sh
```

Or download the latest release from [the releases page](https://codeberg.org/tsukinoko-kun/doctopus/releases).

#### From source

```bash
go install codeberg.org/tsukinoko-kun/doctopus@latest
```

or

```bash
git clone https://codeberg.org/tsukinoko-kun/doctopus
cd doctopus
go install .
```

You need to have Go and GCC installed.

On Windows, only MinGW is supported.
This is because of a Rust dependency.

## License and usage

This program is licensed under the [Zlib license](https://codeberg.org/tsukinoko-kun/doctopus/src/branch/main/LICENSE).

The source code is available on [Codeberg](https://codeberg.org/tsukinoko-kun/doctopus).

You can use this program for free. The default footer contains a link to this website. You are allowed to remove it but I would appreciate it if you left it in.

## Breaking changes

This program is still in an early stage. But breaking changes are unlikely and I will try my best to avoid them.

## Users of Doctopus

- [Bloodmage Software](https://bloodmagesoftware.de/)
- [enyDyne](https://enydyne.de/)

Want to get listed here? [Open an issue](https://codeberg.org/tsukinoko-kun/doctopus/issues/new).

<!--
Sitemap

URL: https://doctopus.frankmayer.dev/index.md
Title: doctopus
Description: The simplest way to write beautiful documentation

URL: https://doctopus.frankmayer.dev/v0.3.0/config.md
Title: Config
Description: Doctopus build configuration.

URL: https://doctopus.frankmayer.dev/v0.3.0/diagrams.md
Title: Diagrams
Description: Different diagram tools.

URL: https://doctopus.frankmayer.dev/v0.3.0/favicon.md
Title: Favicon
Description: How to set a custom favicon for your docs.

URL: https://doctopus.frankmayer.dev/v0.3.0/homepage.md
Title: Homepage
Description: The special homepage (`/index.html`).

URL: https://doctopus.frankmayer.dev/v0.3.0/hooks.md
Title: Hooks
Description: Integrate external tools using pre- and post-build hooks for things like generating files.

URL: https://doctopus.frankmayer.dev/v0.3.0/index.md
Title: Index

URL: https://doctopus.frankmayer.dev/v0.3.0/math.md
Title: Math
Description: LaTeX math support.

URL: https://doctopus.frankmayer.dev/v0.3.0/syntax_highlighting.md
Title: Syntax Highlighting
Description: Code blocks with syntax highlighting.

URL: https://doctopus.frankmayer.dev/v0.3.1/config.md
Title: Config
Description: Doctopus build configuration.

URL: https://doctopus.frankmayer.dev/v0.3.1/diagrams.md
Title: Diagrams
Description: Different diagram tools.

URL: https://doctopus.frankmayer.dev/v0.3.1/favicon.md
Title: Favicon
Description: How to set a custom favicon for your docs.

URL: https://doctopus.frankmayer.dev/v0.3.1/homepage.md
Title: Homepage
Description: The special homepage (`/index.html`).

URL: https://doctopus.frankmayer.dev/v0.3.1/hooks.md
Title: Hooks
Description: Integrate external tools using pre- and post-build hooks for things like generating files.

URL: https://doctopus.frankmayer.dev/v0.3.1/index.md
Title: Index

URL: https://doctopus.frankmayer.dev/v0.3.1/math.md
Title: Math
Description: LaTeX math support.

URL: https://doctopus.frankmayer.dev/v0.3.1/syntax_highlighting.md
Title: Syntax Highlighting
Description: Code blocks with syntax highlighting.

URL: https://doctopus.frankmayer.dev/next/config.md
Title: Config
Description: Doctopus build configuration.

URL: https://doctopus.frankmayer.dev/next/diagrams.md
Title: Diagrams
Description: Different diagram tools.

URL: https://doctopus.frankmayer.dev/next/favicon.md
Title: Favicon
Description: How to set a custom favicon for your docs.

URL: https://doctopus.frankmayer.dev/next/homepage.md
Title: Homepage
Description: The special homepage (`/index.html`).

URL: https://doctopus.frankmayer.dev/next/hooks.md
Title: Hooks
Description: Integrate external tools using pre- and post-build hooks for things like generating files.

URL: https://doctopus.frankmayer.dev/next/math.md
Title: Math
Description: LaTeX math support.

URL: https://doctopus.frankmayer.dev/next/media.md
Title: Media
Description: More than just images.

URL: https://doctopus.frankmayer.dev/next/search.md
Title: Search
Description: Search pages by content.

URL: https://doctopus.frankmayer.dev/next/syntax_highlighting.md
Title: Syntax Highlighting
Description: Code blocks with syntax highlighting.
-->