README.md (view raw)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 |
<div align="center">
## foggymtndrifter.com
[![License]](LICENSE)
</div>
astro-erudite is an opinionated, no-frills static blogging template built with [Astro](https://astro.build/), [Tailwind](https://tailwindcss.com/), and [shadcn/ui](https://ui.shadcn.com/). Extraordinarily loosely based off the [Astro Micro](https://astro-micro.vercel.app/) theme by [trevortylerlee](https://github.com/trevortylerlee).
To learn more about why this template exists, read [The State of Static Blogs in 2024](https://astro-erudite.vercel.app/blog/the-state-of-static-blogs), where I share my take on what constitutes a great blogging template and my goals while developing this one.
---
## Technology Stack
This is a list of the various technologies used to build this website:
| Category | Technology Name |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| Framework | [Astro](https://astro.build/) |
| Styling | [Tailwind](https://tailwindcss.com) |
| Components | [shadcn/ui](https://ui.shadcn.com/) |
| Content | [MDX](https://mdxjs.com/) |
| Syntax Highlighting | [Shiki](https://github.com/shikijs/shiki) + [rehype-pretty-code](https://rehype-pretty.pages.dev/) |
| Graphics | [Figma](https://www.figma.com/) |
| Deployment | [Vercel](https://vercel.com) |
---
## Features
- [Astro](https://astro.build/)’s [Islands](https://docs.astro.build/en/concepts/islands/) architecture for partial/selective hydration and client-side interactivity while maintaining a fast-to-render static site.
- [shadcn/ui](https://ui.shadcn.com/)’s [Tailwind](https://tailwindcss.com/) color convention for automatic styling across both light and dark themes. Includes accessible, theme-aware UI components for navigation, buttons, etc.
- [rehype-pretty-code](https://rehype-pretty.pages.dev/) with [Shiki](https://github.com/shikijs/shiki) for advanced code block styling, highlighting, and code block titles/captions.
- Blog post authoring using [MDX](https://mdxjs.com/) for component-style content, alongside $\LaTeX$ rendering using [KaTeX](https://katex.org/).
- Astro [View Transitions](https://docs.astro.build/en/guides/view-transitions/) in <abbr title="Single Page Application">SPA</abbr> mode for smooth, opt-in animations during route switching.
- SEO optimization with fine-grained control over metadata and [Open Graph](https://ogp.me/) tags for each post.
- [RSS](https://en.wikipedia.org/wiki/RSS) feeds and sitemap generation!
- Supports author profiles (with a dedicated authors page) and adding multiple authors per post.
- Supports project tags (with a dedicated tags page) for easy post categorization and discovery.
## Getting Started
1. Hit “Use this template”, the big green button on the top right, to create a new repository in your own GitHub account with this template.
2. Clone the repository:
```bash
git clone https://github.com/[YOUR_USERNAME]/[YOUR_REPO_NAME].git
cd [YOUR_REPO_NAME]
```
3. Install dependencies:
```bash
npm install
```
4. Start the development server:
```bash
npm run dev
```
5. Open your browser and visit `http://localhost:1234` to get started. The following commands are also available:
| Command | Description |
| ------------------ | --------------------------------------------------------------- |
| `npm run start` | Alias for `npm run dev` |
| `npm run build` | Run type checking and build the project |
| `npm run preview` | Previews the built project |
| `npm run astro` | Run Astro CLI commands |
| `npm run prettier` | Blanket format all files using [Prettier](https://prettier.io/) |
## Customization
### Site Configuration
Edit the `src/consts.ts` file to update your site's metadata, navigation links, and social links:
```typescript
export const SITE: Site = {
TITLE: 'astro-erudite',
DESCRIPTION:
'astro-erudite is a opinionated, no-frills blogging template—built with Astro, Tailwind, and shadcn/ui.',
EMAIL: 'jason@enscribe.dev',
NUM_POSTS_ON_HOMEPAGE: 2,
SITEURL: 'https://astro-erudite.vercel.app',
}
export const NAV_LINKS: Link[] = [
{ href: '/blog', label: 'blog' },
{ href: '/authors', label: 'authors' },
{ href: '/about', label: 'about' },
{ href: '/tags', label: 'tags' },
]
export const SOCIAL_LINKS: Link[] = [
{ href: 'https://github.com/jktrn', label: 'GitHub' },
{ href: 'https://twitter.com/enscry', label: 'Twitter' },
{ href: 'jason@enscribe.dev', label: 'Email' },
{ href: '/rss.xml', label: 'RSS' },
]
```
### Color Palette
Colors are defined in `src/styles/global.css` in [<abbr title="Hue, Saturation, Lightness">HSL</abbr> format](https://en.wikipedia.org/wiki/HSL_and_HSV), using the [shadcn/ui](https://ui.shadcn.com/) convention:
```css
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 0 0% 3.9%;
--primary: 0 0% 9%;
--primary-foreground: 0 0% 98%;
--secondary: 0 0% 80.1%;
--secondary-foreground: 0 0% 9%;
--muted: 0 0% 80.1%;
--muted-foreground: 0 0% 45.1%;
--accent: 0 0% 80.1%;
--accent-foreground: 0 0% 9%;
--additive: 112 50% 36%; /* Unique to astro-erudite */
--additive-foreground: 0 0% 98%; /* Unique to astro-erudite */
--destructive: 0 84.2% 60.2%;
--destructive-foreground: 0 0% 98%;
--border: 0 0% 89.8%;
--ring: 0 0% 3.9%;
}
.dark {
/* ... */
}
/* ... */
}
```
## Adding Content
### Blog Posts
Add new blog posts as MDX files in the `src/content/blog/` directory. Use the following frontmatter structure:
```yml
---
title: 'Your Post Title'
description: 'A brief description of your post!'
date: 2024-01-01
tags: ['tag1', 'tag2']
image: './image.png'
authors: ['author1', 'author2']
draft: false
---
```
The blog post schema is defined as follows:
| Field | Type (Zod) | Requirements | Required |
| ------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `title` | `string` | Must be ≤60 characters. | Yes |
| `description` | `string` | Must be ≤155 characters. | Yes |
| `date` | `coerce.date()` | Must be in `YYYY-MM-DD` format. | Yes |
| `image` | `image()` | Must be exactly 1200px × 630px. | Optional |
| `tags` | `string[]` | Preferably use kebab-case for these. | Optional |
| `authors` | `string[]` | If the author has a profile, use the slug associated with their Markdown file in `src/content/authors/` (e.g. if their file is named `jane-doe.md`, use `jane-doe` in the array). | Optional |
| `draft` | `boolean` | Defaults to `false` if not provided. | Optional |
### Authors
Add author information in `src/content/authors/` as Markdown files. A file named `[author-name].md` can be associated with a blog post if `"author-name"` (the slug) is added to the `authors` field:
```yml
---
name: 'enscribe'
pronouns: 'he/him'
avatar: 'https://gravatar.com/avatar/9bfdc4ec972793cf05cb91efce5f4aaaec2a0da1bf4ec34dad0913f1d845faf6.webp?size=256'
bio: 'd(-_-)b'
website: 'https://enscribe.dev'
twitter: 'https://twitter.com/enscry'
github: 'https://github.com/jktrn'
mail: 'jason@enscribe.dev'
---
```
The author schema is defined as follows:
| Field | Type (Zod) | Requirements | Required |
| ---------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `name` | `string` | n/a | Yes |
| `pronouns` | `string` | n/a | Optional |
| `avatar` | `string.url()` | Must be a valid URL. Preferably use [Gravatar](https://en.gravatar.com/site/implement/images/) with the `?size=256` size parameter. | Yes |
| `bio` | `string` | n/a | Optional |
| `mail` | `string.email()` | Must be a valid email address. | Optional |
| `website` | `string.url()` | Must be a valid URL. | Optional |
| `twitter` | `string.url()` | Must be a valid URL. | Optional |
| `github` | `string.url()` | Must be a valid URL. | Optional |
| `linkedin` | `string.url()` | Must be a valid URL. | Optional |
| `discord` | `string.url()` | Must be a valid URL. | Optional |
You can add as many social media links as you want, as long as you adjust the schema! Make sure you also support the new field in the `src/components/SocialIcons.astro` component.
### Projects
Add projects in `src/content/projects/` as Markdown files:
```yml
---
name: 'Project A'
description: 'This is an example project description! You should replace this with a description of your own project.'
tags: ['Framework A', 'Library B', 'Tool C', 'Resource D']
image: '/static/1200x630.png'
link: 'https://example.com'
---
```
The project schema is defined as follows:
| Field | Type (Zod) | Requirements | Required |
| ------------- | -------------- | ------------------------------------- | -------- |
| `name` | `string` | n/a | Yes |
| `description` | `string` | n/a | Yes |
| `tags` | `string[]` | n/a | Yes |
| `image` | `image()` | Must be exactly 1200px × 630px. | Yes |
| `link` | `string.url()` | Must be a valid URL. | Yes |
## License
This project is open source and available under the [MIT License](LICENSE).
---
Built with ♥ by [enscribe](https://enscribe.dev)!
[Stargazers]: https://img.shields.io/github/stars/jktrn/astro-erudite?color=fafafa&logo=github&logoColor=fff&style=for-the-badge
[License]: https://img.shields.io/github/license/jktrn/astro-erudite?color=0a0a0a&logo=github&logoColor=fff&style=for-the-badge
|