Contributing

Contributions are welcome: bug fixes, new features, documentation improvements, and accessibility fixes alike.

Development setup

To get started, install Bun (opens in new tab) ≥ 1.1.

git clone https://github.com/amousavigourabi/folio.md.git
cd folio-md
bun install
bun run dev

The dev server starts at http://localhost:4321 and hot-reloads on every file save.

bun install also installs Lefthook (opens in new tab) git hooks automatically. Two hooks are active:

• pre-commit: runs bun run check before every commit, which covers linting and TypeScript type checking
• pre-push: runs bun run test before every push, so test failures don’t reach the remote

Code style

folio.md uses Biome (opens in new tab) for linting and formatting. Run it before pushing:

bun run lint        # check
bun run lint:fix    # auto-fix
bun run check       # lint + TypeScript type check together

Key conventions Biome enforces:

• 2-space indentation
• Double quotes for strings
• Trailing commas everywhere they’re valid
• Imports auto-organized on save

TypeScript uses strict mode from astro/tsconfigs/strict. Avoid any. Prefer explicit types on public-facing APIs.

Before opening a pull request

• Run the linter and type check: bun run check
• Run the tests: bun run test, or bun run test:coverage for a coverage report
• Validate links: bun run build runs the link checker automatically
• Check both themes: if your change touches the UI, verify it in both light and dark mode
• Check mobile: resize below 1024 px and confirm the mobile drawer and search bar still work

Adding a Lucide icon

Icons available in the icon page setting come from src/components/NavIcon.tsx. To add one:

1. Import it from lucide-react
2. Add it to the icons map in the same file

See the Icon Reference for the current list.

Submitting changes

Open a pull request against master. Keep PRs focused: one logical change per PR makes review faster. Include a short description of what changed and why.