Darkness is a free, open-source portfolio and blog theme for Astro, distinguished by a live 5,000-particle Three.js background, and it outputs a static site from Markdown or MDX content.
What is Darkness?
Darkness is a portfolio and blog template built on Astro 6, using TypeScript and Three.js. It takes content written as Markdown or MDX files in the src/content directory and generates a static, search-engine-optimized website with a dark glassmorphism aesthetic. The theme is created by kpab and released under the MIT license, and it can be deployed to Vercel or Netlify with one click.
Key Features
- Three.js particle starfield — 5,000 GPU-accelerated particles animate and react to scroll, powered by Three.js version 0.184.
- Blog via Content Collections — posts live in src/content/blog with frontmatter fields for title, description, publication date, and tags; content supports Markdown and MDX.
- Portfolio project showcase — each project is a Markdown file in src/content/projects with fields for title, description, GitHub URL, tags, and a featured flag.
- Responsive mobile-first design — the layout includes a floating navigation bar and adapts to small screens.
- CSS-variable theming — colors and fonts are configured from a handful of variables in src/styles/global.css, including Space Grotesk for headings and DM Sans for body text.
- Zero client-side JS by default — Astro 6 sends no JavaScript unless a component explicitly needs it, and the theme ships with sitemap and SEO meta.
- TypeScript content contracts — content collections and components are type-checked to catch missing fields.
Who is it for?
- Front-end developers — they can clone the repository, install dependencies with npm install, run the dev server with npm run dev, and start writing Markdown content immediately.
- Portfolio-driven creators — designers, writers, and photographers who want a visually distinct dark site and can customize the look via CSS variables.
- Static-blog authors — people who want a blog with MDX support, tag-based posts, and a built-in project gallery without managing a CMS.
What can you do with Darkness?
- Launch a personal portfolio: create project entries in src/content/projects, set the featured flag to lift key projects to the showcase, and link each project to a GitHub repository.
- Publish a blog: add Markdown or MDX files to src/content/blog with title, description, pubDate, and tags; the theme renders a chronologically ordered blog from Content Collections.
- Deploy in one click: use the provided Vercel or Netlify buttons to deploy the repository without configuring a build pipeline.
How does Darkness work?
The quick-start flow is a standard Astro workflow: clone the repository from https://github.com/kpab/astro-darkness, run npm install, then npm run dev for local development or npm run build to generate the production static site. The build requires Node.js version 22 or higher, matching Astro 6's requirement. The generated output is a fully static site ready to host anywhere.
FAQ
Is Darkness free to use?
Yes, Darkness is open source under the MIT license, so it can be used for personal and commercial projects without payment.
What Node.js version is required?
The theme requires Node.js 22 or newer because it builds on Astro 6.
Can I customize the colors and fonts?
Yes. The design tokens are defined as CSS variables in src/styles/global.css — for example, the background color, primary color, accent purple, and the two Google Fonts Space Grotesk and DM Sans — so the entire look can be changed in one place.
