Developer Contributions

We want developers of all skill levels to contribute to Plain License. Whether you’re a beginner or an expert, there are many ways you can help us make licenses easier to understand.

• Submit an Issue: Suggest a feature, fix a styling or rendering bug, or improve our build process. You can submit an issue on our GitHub Issues page ➚. Be sure to include a clear description of the problem and any ideas for how to fix it.
• Submit a Pull Request: If you’re comfortable with Git and GitHub, you can submit a pull request to fix an issue or add a new feature. We welcome contributions of all sizes, from small typo fixes to large feature additions. Any big changes should start with an issue ➚ to discuss what you have in mind.
• Refactor Our Code: If you enjoy cleaning up code, we have plenty of opportunities for you to help. Refactoring can help improve the readability, maintainability, and performance of our codebase.

Getting Started

We use a special commit message format to help us keep track of changes. Before you start contributing, please read our commit message guidelines. If you mess it up, don’t worry! We can fix it later. But it’s best to get it right the first time. Setting Up Your Environment. We use mise ➚ to manage tools and tasks, and Bun ➚ as our package manager. To get started:

1. Install mise ➚ and Bun ➚ if you don’t have them.
2. Clone the repository and cd into it.
3. Run mise run setup — this installs dependencies, sets up git hooks, and creates the needed symlinks.

That’s it! You’re ready to start developing. Here are the commands you’ll use most:

A Tour of Our Codebase

• Framework: We use Astro 5 ➚ with the Starlight ➚ documentation theme. Astro builds fast, static sites from components and content collections. Most of what you see on the site comes from Markdown content files and Astro components.

• Content: All content lives in the content/ directory:

  • content/licenses/{category}/{spdx-id}.md — license pages with YAML frontmatter
  • content/blog/ — blog posts
  • content/mappings/ — term mappings between original and plain license language

  License categories are: permissive, copyleft, source-available, and public-domain.

• Components: Interactive and layout components live in src/components/:

  • src/components/overrides/ — Starlight layout overrides (Header, Footer, Sidebar)
  • src/components/reactive/ — interactive Preact components (LicenseFinder, ComparisonTable, FAQ)
  • src/components/*.astro — license-specific components (LicenseSummary, DownloadOptions, VersionHistory)

• Pages: Static pages (like this one) live in src/pages/. They use .mdx or .astro files.

• Schemas & Types: Content schemas are defined in src/content.config.ts. Type definitions live in src/_types/.

• Build Pipeline: mise run build runs astro build followed by three post-build scripts:

  1. src/build/generate-exports.ts — creates downloadable license files (MD, PDF, TXT)
  2. src/build/generate-og-images.ts — creates social share images

• URL Routing: License URLs are auto-generated at build time. Adding a file at content/licenses/{category}/{spdx-id}.md automatically creates short URLs like /licenses/{spdx-id} and /{spdx-id} that redirect to the full path.

• Monorepo Packages: Each license has a workspace package in packages/{spdx-id}/ with its own package.json for independent versioning. See Adding a License for the full process.

• Linting & Formatting: Biome ➚ handles TypeScript, JavaScript, JSON, and CSS linting and formatting. Configuration is in biome.jsonc.

• CI/CD: We use GitHub Actions for our CI/CD process. Workflow files are in .github/workflows/, and supporting scripts are in .github/scripts/.

• Deployment: The site deploys to Cloudflare Pages ➚. The configuration is in wrangler.json.

Key Config Files