git.stevedylan.dev

README.md 8.4 K raw

<div align="center">
  <img alt="Astro Theme Cactus logo" src="./gh-assets/astro-cactus-logo.png" width="70" />
</div>
<h1 align="center">
  🚀 Astro Theme Cactus 🌵
</h1>

Astro Theme Cactus is a simple opinionated starter built with the Astro framework. Use it to create an easy-to-use blog or website.

## Key Features

- Astro Fast 🚀
- TailwindCSS Utility classes
- Accessible, semantic HTML markup
- Responsive & SEO-friendly
- Dark / Light mode, using Tailwind and CSS variables
- [Astro Image Integration](https://docs.astro.build/en/guides/integrations-guide/image/) for optimised images
- MD & [MDX](https://docs.astro.build/en/guides/markdown-content/#mdx-only-features) posts
- [Satori](https://github.com/vercel/satori) for creating open graph png images.
- Pagination
- [Automatic RSS feed](https://docs.astro.build/en/guides/rss)
- Shiki code syntax styling
- Auto-generated [sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/)

## Demo 💻

Check out the [Demo](https://astro-theme-cactus.netlify.app/), hosted on Netlify

## Quick start

[Create a new repo](https://github.com/chrismwilliams/astro-theme-cactus/generate) from this template.

[![Deploy with Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/chrismwilliams/astro-theme-cactus) [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fchrismwilliams%2Fastro-theme-cactus&project-name=astro-theme-cactus)

## Commands

Replace pnpm with your choice of npm / yarn

| Command        | Action                                                         |
| :------------- | :------------------------------------------------------------- |
| `pnpm install` | Installs dependencies                                          |
| `pnpm dev`     | Starts local dev server at `localhost:3000`                    |
| `pnpm build`   | Build your production site to `./dist/`                        |
| `pnpm preview` | Preview your build locally, before deploying                   |
| `pnpm sync`    | Generate types based on your config in `src/content/config.ts` |

## Configure

- Edit the config file `src/site.config.ts` for basic site meta data
- Update file `astro.config.ts` site property with your own domain
- Replace & update files within the `/public` folder:
  - favicon.ico & other social icons
  - robots.txt - update the Sitemap url to your own domain
  - manifest.webmanifest
- Modify file `src/styles/global.css` with your own light and dark styles
- Edit social links in `src/data/constants.ts` and in turn `src/components/SocialList.astro` to add/replace your media profile. Icons used can be found @ [tablericons](https://tablericons.com/)
- Create / edit posts for your blog within `src/content/post/` with .md/mdx file(s). See [below](#adding-posts) for more details.
- OG Image:
  - If you would like to change the style of the generated image the Satori library creates, open up `src/pages/og-image/[slug].png.ts` to the markup function where you can edit the html/tailwind-classes as necessary. You can also use this [satori playground](https://og-playground.vercel.app/) to aid your design.
  - If you would like to generate svg og images rather than the default .png ones, you will need to remove the @resvg/resvg-js library, and return the svg within the body of the get function from the file `src/pages/og-image/[slug].png.ts`.
  - You can also create your own og images and skip satori generating if for you by adding an ogImage property in the frontmatter with a link to the asset, an example can be found in `src/content/post/social-image.md`. More info on frontmatter can be found [here](#frontmatter)
- Optional:
  - Fonts: This theme sets the body element to the font family `font-mono`, located in the global css file `src/styles/global.css`. You can change fonts by removing the variant `font-mono`, after which TailwindCSS will default to the `font-sans` [font family stack](https://tailwindcss.com/docs/font-family).

## Adding posts

This theme utilises [Content Collections](https://docs.astro.build/en/guides/content-collections/) to organise Markdown and/or MDX files, as well as type-checking frontmatter with a schema -> `src/content/config.ts`.

Adding a post is a simple as adding your .md(x) file(s) to the `src/content/post` folder, the filename of which will be used as the slug/url. The two posts included with this template are there as an example of how to structure your frontmatter. Additionally, the [Astro docs](https://docs.astro.build/en/guides/markdown-content/) has a detailed section on markdown pages.

### Frontmatter

| Property (\* required) | Description                                                                                                                                                                                                                                                                                       |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| title \*               | Self explanatory. Used as the text link to the post, the h1 on the posts' page, and the pages title property. Has a max length of 60 chars, set in `src/content/config.ts`                                                                                                                        |
| description \*         | Similar to above, used as the seo description property. Has a min length of 50 and a max length of 160 chars, set in the post schema.                                                                                                                                                             |
| publishDate \*         | Again pretty simple. To change the date format/locale, currently **en-GB**, update/pass the **locale** arg to function **getFormattedDate**, found in `src/utils/date.ts`.                                                                                                                        |
| tags                   | Tags are optional with any created post. Any new tag(s) will be shown in `yourdomain.com/posts` + `yourdomain.com/tags`, and generate the page(s) `yourdomain.com/tags/[yourTag]`                                                                                                                 |
| ogImage                | This is an optional property. An OG Image will be generated automatically for every post where this property **isn't** provided. If you would like to create your own for a specific post, include this property and a link to your image, the theme will then skip automatically generating one. |

## Analytics

You may want to track the number of visitors you receive to your blog/website in order to understand trends and popular posts/pages you've created. There are a number of providers out there one could use, including web hosts such as [vercel](https://vercel.com/analytics), [netlify](https://www.netlify.com/products/analytics/), and [cloudflare](https://www.cloudflare.com/web-analytics/).

This theme/template doesn't include a specific solution due to there being a number of use cases and/or options which some people may or may not use.

You may be asked to included a snippet inside the **HEAD** tag of your website when setting it up, which can be found in `src/layouts/Base.astro`. Alternatively, you could add the snippet in `src/components/BaseHead.astro`.

Another popular provider is google analytics which you could integrate via the above method, or, for example adding [astro-google-analytics](https://www.npmjs.com/package/astro-google-analytics)

```bash
pnpm install astro-google-analytics
```

Edit `src/layouts/Base.astro`, and add:

```tsx
---
import { GoogleAnalytics } from 'astro-google-analytics';
// ...other imports
---

<head>
  <!-- Replace id with your own Google Analytics ID -->
  <GoogleAnalytics id="G-XXXXXXXXXX" />
</head>
```

## Deploy

[Astro docs](https://docs.astro.build/en/guides/deploy/) has a great section and breakdown of how to deploy your own Astro site on various platforms and their idiosyncrasies.

By default the site will be built (see [Commands](#commands) section above) to a `/dist` directory.

## Acknowledgment

This theme is inspired by [Hexo Theme Cactus](https://github.com/probberechts/hexo-theme-cactus)

## License

MIT

1	<div align="center">
2	<img alt="Astro Theme Cactus logo" src="./gh-assets/astro-cactus-logo.png" width="70" />
3	</div>
4	<h1 align="center">
5	🚀 Astro Theme Cactus 🌵
6	</h1>
7
8	Astro Theme Cactus is a simple opinionated starter built with the Astro framework. Use it to create an easy-to-use blog or website.
9
10	## Key Features
11
12	- Astro Fast 🚀
13	- TailwindCSS Utility classes
14	- Accessible, semantic HTML markup
15	- Responsive & SEO-friendly
16	- Dark / Light mode, using Tailwind and CSS variables
17	- [Astro Image Integration](https://docs.astro.build/en/guides/integrations-guide/image/) for optimised images
18	- MD & [MDX](https://docs.astro.build/en/guides/markdown-content/#mdx-only-features) posts
19	- [Satori](https://github.com/vercel/satori) for creating open graph png images.
20	- Pagination
21	- [Automatic RSS feed](https://docs.astro.build/en/guides/rss)
22	- Shiki code syntax styling
23	- Auto-generated [sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/)
24
25	## Demo 💻
26
27	Check out the [Demo](https://astro-theme-cactus.netlify.app/), hosted on Netlify
28
29	## Quick start
30
31	[Create a new repo](https://github.com/chrismwilliams/astro-theme-cactus/generate) from this template.
32
33	[![Deploy with Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/chrismwilliams/astro-theme-cactus) [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fchrismwilliams%2Fastro-theme-cactus&project-name=astro-theme-cactus)
34
35	## Commands
36
37	Replace pnpm with your choice of npm / yarn
38
39	\| Command \| Action \|
40	\| :------------- \| :------------------------------------------------------------- \|
41	\| `pnpm install` \| Installs dependencies \|
42	\| `pnpm dev` \| Starts local dev server at `localhost:3000` \|
43	\| `pnpm build` \| Build your production site to `./dist/` \|
44	\| `pnpm preview` \| Preview your build locally, before deploying \|
45	\| `pnpm sync` \| Generate types based on your config in `src/content/config.ts` \|
46
47	## Configure
48
49	- Edit the config file `src/site.config.ts` for basic site meta data
50	- Update file `astro.config.ts` site property with your own domain
51	- Replace & update files within the `/public` folder:
52	- favicon.ico & other social icons
53	- robots.txt - update the Sitemap url to your own domain
54	- manifest.webmanifest
55	- Modify file `src/styles/global.css` with your own light and dark styles
56	- Edit social links in `src/data/constants.ts` and in turn `src/components/SocialList.astro` to add/replace your media profile. Icons used can be found @ [tablericons](https://tablericons.com/)
57	- Create / edit posts for your blog within `src/content/post/` with .md/mdx file(s). See [below](#adding-posts) for more details.
58	- OG Image:
59	- If you would like to change the style of the generated image the Satori library creates, open up `src/pages/og-image/[slug].png.ts` to the markup function where you can edit the html/tailwind-classes as necessary. You can also use this [satori playground](https://og-playground.vercel.app/) to aid your design.
60	- If you would like to generate svg og images rather than the default .png ones, you will need to remove the @resvg/resvg-js library, and return the svg within the body of the get function from the file `src/pages/og-image/[slug].png.ts`.
61	- You can also create your own og images and skip satori generating if for you by adding an ogImage property in the frontmatter with a link to the asset, an example can be found in `src/content/post/social-image.md`. More info on frontmatter can be found [here](#frontmatter)
62	- Optional:
63	- Fonts: This theme sets the body element to the font family `font-mono`, located in the global css file `src/styles/global.css`. You can change fonts by removing the variant `font-mono`, after which TailwindCSS will default to the `font-sans` [font family stack](https://tailwindcss.com/docs/font-family).
64
65	## Adding posts
66
67	This theme utilises [Content Collections](https://docs.astro.build/en/guides/content-collections/) to organise Markdown and/or MDX files, as well as type-checking frontmatter with a schema -> `src/content/config.ts`.
68
69	Adding a post is a simple as adding your .md(x) file(s) to the `src/content/post` folder, the filename of which will be used as the slug/url. The two posts included with this template are there as an example of how to structure your frontmatter. Additionally, the [Astro docs](https://docs.astro.build/en/guides/markdown-content/) has a detailed section on markdown pages.
70
71	### Frontmatter
72
73	\| Property (\* required) \| Description \|
74	\| :--------------------- \| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ \|
75	\| title \* \| Self explanatory. Used as the text link to the post, the h1 on the posts' page, and the pages title property. Has a max length of 60 chars, set in `src/content/config.ts` \|
76	\| description \* \| Similar to above, used as the seo description property. Has a min length of 50 and a max length of 160 chars, set in the post schema. \|
77	\| publishDate \* \| Again pretty simple. To change the date format/locale, currently en-GB, update/pass the locale arg to function getFormattedDate, found in `src/utils/date.ts`. \|
78	\| tags \| Tags are optional with any created post. Any new tag(s) will be shown in `yourdomain.com/posts` + `yourdomain.com/tags`, and generate the page(s) `yourdomain.com/tags/[yourTag]` \|
79	\| ogImage \| This is an optional property. An OG Image will be generated automatically for every post where this property isn't provided. If you would like to create your own for a specific post, include this property and a link to your image, the theme will then skip automatically generating one. \|
80
81	## Analytics
82
83	You may want to track the number of visitors you receive to your blog/website in order to understand trends and popular posts/pages you've created. There are a number of providers out there one could use, including web hosts such as [vercel](https://vercel.com/analytics), [netlify](https://www.netlify.com/products/analytics/), and [cloudflare](https://www.cloudflare.com/web-analytics/).
84
85	This theme/template doesn't include a specific solution due to there being a number of use cases and/or options which some people may or may not use.
86
87	You may be asked to included a snippet inside the HEAD tag of your website when setting it up, which can be found in `src/layouts/Base.astro`. Alternatively, you could add the snippet in `src/components/BaseHead.astro`.
88
89	Another popular provider is google analytics which you could integrate via the above method, or, for example adding [astro-google-analytics](https://www.npmjs.com/package/astro-google-analytics)
90
91	```bash
92	pnpm install astro-google-analytics
93	```
94
95	Edit `src/layouts/Base.astro`, and add:
96
97	```tsx
98	---
99	import { GoogleAnalytics } from 'astro-google-analytics';
100	// ...other imports
101	---
102
103	<head>
104	<!-- Replace id with your own Google Analytics ID -->
105	<GoogleAnalytics id="G-XXXXXXXXXX" />
106	</head>
107	```
108
109	## Deploy
110
111	[Astro docs](https://docs.astro.build/en/guides/deploy/) has a great section and breakdown of how to deploy your own Astro site on various platforms and their idiosyncrasies.
112
113	By default the site will be built (see [Commands](#commands) section above) to a `/dist` directory.
114
115	## Acknowledgment
116
117	This theme is inspired by [Hexo Theme Cactus](https://github.com/probberechts/hexo-theme-cactus)
118
119	## License
120
121	MIT