astro-humans

astro-humans

Standards‑friendly humans.txt generation for Astro sites

astro-humans is a static‑first Astro integration that generates a clean, human‑readable humans.txt file at build time.

It exists for one reason:

The internet is for humans.
This file documents the people and tools behind a website.

No runtime JavaScript.
No tracking.
No build coupling.
No opinionated enforcement.

What this plugin does

On astro build, the plugin:

• Ensures a humans.config.json file exists (first run only)
• Supports automatic migration from legacy root config → config-files/
• Loads and normalises configuration safely (fail‑closed)
• Generates a deterministic humans.txt
• Writes to:
  • /humans.txt (canonical)
  • /.well-known/humans.txt (optional)
• Overwrites output files deterministically on each build

What this plugin does NOT do

• ❌ No runtime middleware
• ❌ No validation policing
• ❌ No schema enforcement beyond safety
• ❌ No auto‑population or guessing
• ❌ No ownership claims or legal statements

If configuration is invalid or disabled, no file is written.

Installation

npm install astro-humans

Usage

Add the integration to your Astro config:

import { defineConfig } from "astro/config";
import astroHumans from "astro-humans";

export default defineConfig({
  integrations: [
    astroHumans()
  ]
});

Configuration location

On first run, the plugin ensures this file exists:

config-files/humans.config.json

Automatic migration

If a legacy file exists at:

/humans.config.json

It will be moved automatically to:

/config-files/humans.config.json

This happens once and never overwrites existing files.

Example configuration

{
  "enabled": true,
  "output": {
    "wellKnown": false,
    "root": true
  },
  "humans": {
    "team": [
      {
        "name": "Your Name",
        "role": "Developer",
        "contact": "https://example.com"
      }
    ],
    "site": {
      "name": "Example Website",
      "url": "https://example.com",
      "language": "en",
      "lastUpdated": "2026-01-01"
    },
    "technology": [
      "Astro",
      "TypeScript",
      "HTML",
      "CSS"
    ],
    "notes": [
      "Built with care.",
      "The internet is for humans."
    ]
  }
}

Generated output

/* TEAM */
Name: Your Name
Role: Developer
Contact: https://example.com

/* SITE */
Name: Example Website
URL: https://example.com
Language: en
Last Updated: 2026-01-01

/* TECHNOLOGY */
Astro
TypeScript
HTML
CSS

/* NOTES */
Built with care.
The internet is for humans.

Sections (optional)

All sections are optional and omitted if empty:

• TEAM – People involved in building the site
• SITE – Basic site metadata
• TECHNOLOGY – Tools and platforms used
• NOTES – Human‑readable comments

There is no required schema beyond basic safety.

Failure behaviour

This plugin is intentionally fail‑silent.

If any of the following occur:

• Config file missing
• JSON invalid
• enabled: false

➡️ No humans.txt is written

Your build will continue normally.

Philosophy

• Humans.txt is not a legal document
• Humans.txt is not ownership proof
• Humans.txt is not machine‑enforced

It is a courtesy file — nothing more, nothing less.

License

MIT © Velohost UK Limited

Author

Built and maintained by Velohost UK Limited https://velohost.co.uk/

Project homepage:
https://velohost.co.uk/plugins/astro-humans/