This is an evolution on my personal site. The previous version was built on Jekyll. This one is built on Astro.
- Simple
- Beautiful
- Authenntic
- Content-first
- Use defaults wherever possible.
- Write as little code as possible.
- Optimize for DX (and ease of maintainance and writing).
- Do not over-abstract. Avoid fallbacks, polyfills and hacks.
- Bake accessibility in.
- As few dependencies as possible.
├── public/
│ └── favicon.svg
├── src/
│ └── pages/
│ | ├── index.astro
│ | ├── about.astro
│ | └── writing/
| | ├── my-article.mdx
| | ├── my-other-article.md
| | └── my-fancy-custom-magazine-essay.astro
│ ├── components/
│ │ └── Card.astro
│ ├── layouts/
│ │ └── BaseLayout.astro
│ │ └── ArticleLayout.astro
│ └── scripts/
│ | └── script.ts
│ └── styles/
│ └── global.css
└── package.json
Astro looks for .astro
, .md
or .mdx
files in the src/pages/
directory. Each page is exposed as a route based on its file name. There's nothing special about the other directories in src
, but we follow the conventions in the Astro docs for structure.
Netlify functions live in netlify/functions
and can be ran localy with netlify functions:serve
.
The following hand-rolled "base" components are available for use in other pages/articles etc (not an exhaustive list)...
- Primatives
- Button
- Icon
- Card
Default to Astro components wherever possible, except for long-form writing. This means that most pages, layouts and UI components should be Astro components.
- Keep global styles to a minimum. Components should always use Astro's scoped styles.
- Use CSS Custm Properties on
:root
for global colours and other design tokens. - Components should never affect things outside of them – no margins etc.
- Default CSS Grid for layout and spacing. Fall back to flexbox where it makes for significantly less code.
- Use component queries over media queries, except in layouts.
- All JS should be typescript, whether or not you include type definitions.
- Use modern Javascript and favour readability.
- If possible, use CSS & custom properties for UI interaction stuff.
- For simple things, default to vanilla JS scoped to the Astro component.
- Avoid shipping any global javascript (ie in
src/scripts/
). - Only reach for a React component when you really need it.
We use the following Astro Integrations
Integration | Description | Installed |
---|---|---|
@astrojs/image | Optimising images and providing <Image/> and <Picture/> components. |
[ ] |
@astrojs/mdx | Allows the use of Astro & React components in markdown files | [ ] |
@astrojs/prefetch | Speed. Adds a prefetch script to all pages so `rel="prefetch" works | [ ] |
@astrojs/sitemap | Generates a sitemap based on routes | [ ] |
@astrojs/netlify | Enables Netlify serverless functions | [ ] |
@astrojs/rss | Generating an RSS feed | [ ] |
All commands are run from the root of the project, from a terminal:
Command | Action |
---|---|
pnpm install |
Installs dependencies |
pnpm run dev |
Starts local dev server at localhost:3000 |
pnpm run build |
Build your production site to ./dist/ |
pnpm run preview |
Preview your build locally, before deploying |
pnpm run astro ... |
Run CLI commands like astro add , astro check |
pnpm run astro --help |
Get help using the Astro CLI |