Added initial mkdocs files.

This commit is contained in:
Andrew Lalis 2026-03-31 20:34:09 -04:00
parent 4338ba2c2d
commit 99eef1d617
5 changed files with 92 additions and 0 deletions

5
.gitignore vendored Normal file
View File

@ -0,0 +1,5 @@
# Ignore Python virtual environment.
.env/
# Ignore mkdocs build dir.
site/
.cache/

View File

@ -2,3 +2,16 @@
This repository contains the source code for the Handy-Http website that is
used to showcase the project and provide easy access to documentation.
The website is built using MkDocs, and we develop it in a Python [virtual
environment](https://docs.python.org/3/library/venv.html).
## Setup
```shell
python3 -m venv .env
source .env/bin/activate
pip install mkdocs
pip install mkdocs-material
```
To exit the Python virtual environment, type `deactivate` in your shell.

28
docs/getting-started.md Normal file
View File

@ -0,0 +1,28 @@
# Getting Started
The easiest way to get started is to use the [starter](https://git.andrewlalis.com/Handy-Http/starter)
dependency, which automatically includes the components needed to boot up a
simple HTTP server.
In the example below, we create a new D project named **my-server**, and add
the `handy-http-starter` dependency to it.
```shell
dub init my-server
cd my-server
dub add handy-http-starter
```
Then, edit your main D function like so:
```d title="main.d"
import handy_http_starter;
void main() {
startServer((ref request, ref response) {
response.headers.add("Content-Type", "text/plain");
response.headers.add("Content-Length", "12");
response.outputStream.write(cast(ubyte[]) "Hello world!")
});
}
```
In the above code, we take advantage of Handy-Http Starter's shortcuts to quickly boot up an HTTP server on `http://localhost:8080` that responds to any request with `Hello world!`, by executing the provided [delegate function](https://tour.dlang.org/tour/en/basics/delegates) whenever a request is received.

7
docs/index.md Normal file
View File

@ -0,0 +1,7 @@
# Home
Welcome to the documentation site for Handy-Http. Here you'll find guides on how to get started with writing D web servers using Handy-Http, as well as detailed reference documentation for each of the various components that make up the project.
## About Handy-Http
Handy-Http is a collection of [D lang](https://dlang.org/) source libraries that provide a means for you to run an HTTP server. It started originally as an all-in-one hobby project that Andrew created a few years ago to escape from the clutches of Java's Spring ecosystem. D offers arguably better developer ergonomics, as well as monumental performance improvements due to its static compilation to machine code. Since its inception, it's gone through a few iterations before settling on the modular architecture presented here.

39
mkdocs.yml Normal file
View File

@ -0,0 +1,39 @@
site_name: Handy-Http
site_url: https://handy-http.andrewlalis.com
nav:
- Home: index.md
- Getting Started: getting-started.md
theme:
name: material
palette:
# Palette toggle for automatic mode
- media: "(prefers-color-scheme)"
toggle:
icon: material/brightness-auto
name: Switch to light mode
# Palette toggle for light mode
- media: "(prefers-color-scheme: light)"
scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
# Palette toggle for dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
toggle:
icon: material/brightness-4
name: Switch to system preference
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
plugins:
- privacy