150 lines
No EOL
6.1 KiB
Markdown
150 lines
No EOL
6.1 KiB
Markdown
# Mercury
|
|
|
|
Terminal-like blog theme built from [Astro](https://astro.build), still in early beta.
|
|
|
|
Demo: https://icy-beach-00f5be01e.6.azurestaticapps.net/
|
|
|
|
> 🧑🚀 **Seasoned astronaut?** Delete this file. Have fun!
|
|
|
|
## 🌌 Features
|
|
- Minimal, terminal like
|
|
- Ship only necessary JavaScript (even can be no JavaScript at all)
|
|
- Full text search ~~based on `Fuse.js`~~
|
|
- Full text RSS
|
|
- Create Blogrolls via a yaml file
|
|
- Your status at Fediverse, now at your home
|
|
- Comments powered by multiple engines
|
|
- Umami/Goatcounter statics support
|
|
- TeX formulas support
|
|
|
|
## 🚀 Getting Started
|
|
clone the repo and install dependencies:
|
|
|
|
```bash
|
|
git clone https://git.gb0.dev/gb/mercury.git
|
|
```
|
|
```bash
|
|
cd mercury && pnpm install
|
|
```
|
|
run the dev server:
|
|
|
|
```bash
|
|
pnpm run dev
|
|
```
|
|
open [localhost:4321](http://localhost:4321) in your browser.
|
|
|
|
## 🔧 Usage
|
|
All you need is editing the `astro.config.mjs`'s site & base.
|
|
|
|
For further config, edit `src/config.ts` according to the comment.
|
|
|
|
To start writing, put your markdown & mdx files to /src/content/posts folder.
|
|
|
|
To create a page, put markdown files into /src/content/pages folder.
|
|
|
|
Shortcode-like components is also available at /src/components/shortcodes folder.
|
|
|
|
## 🧞 Commands
|
|
|
|
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:4321` |
|
|
| `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 |
|
|
|
|
## 🗺 Roadmap
|
|
- [x] Initial project setup
|
|
- [x] Basic theme implementation
|
|
- [x] Better full-text search without `Fuse.js`
|
|
- [x] A mode to make the site 0 javascript
|
|
- [x] Multiple authors via YAML
|
|
- [ ] i18n support
|
|
- [x] UI text
|
|
- [ ] Localized content (we need help!)
|
|
- [ ] Translations (we need help!)
|
|
- [x] Better support for printing version
|
|
- [ ] Add support for more comment engines
|
|
- [x] Add support for umami statics
|
|
- [x] Improve documentation
|
|
- [ ] Release v1.0
|
|
- [ ] ~~Integrate with Fediverse w/ activityPub~~
|
|
- [ ] ~~Plain text version when visiting the site via `curl`~~ (can't be done with SSG mode)
|
|
|
|
## ⚙️ Advanced Usage
|
|
### i18n
|
|
I have implemented i18n support for UI text, but not for content translations yet.
|
|
|
|
To further implement i18n, you can:
|
|
1. Create a new folder under `src/content/posts/` with the language code as the name (e.g., `en`, `zh-CN`, etc.).
|
|
2. Copy your translated markdown files into the new folder.
|
|
3. Copy the `src/pages/blog/` folder to `src/pages/[langcode]/blog`.
|
|
4. Update the i18n config in `astro.config.mjs` to include the new language code.
|
|
5. Rebuild the site.
|
|
### plain text version when visiting the site via `curl`
|
|
The text version of the site is generated by `src/pages/blog/[slug].txt.js`, which outputs a plain text version of the blog post.
|
|
To access it, you can visit `https://your-site.com/blog/your-post-slug.txt`.
|
|
|
|
To automatically output the text version when visiting the site via `curl`, you can:
|
|
1. If you are using caddy, add the following to your `Caddyfile`:
|
|
```caddyfile
|
|
@curl {
|
|
header_regexp User-Agent (?i)curl
|
|
}
|
|
@text {
|
|
path_regexp text /blog/(.*)
|
|
}
|
|
handle @curl {
|
|
rewrite @text /blog/{http.regexp.text.1}.txt
|
|
}
|
|
```
|
|
2. If you are using cloudflare to proxy your site, you can add a page rule to redirect requests with the `curl` user agent to the `.txt` version of the blog post:
|
|
If incoming requests match (Custom filter expression):
|
|
```
|
|
(http.request.full_uri wildcard r"https://yourblog/blog/*" and http.user_agent contains "curl")
|
|
```
|
|
Then (Rewrite to,static):
|
|
```
|
|
/blog/${1}.txt
|
|
```
|
|
3. If you are using other web servers, you can use functions like `rewrite` or `redirect` by user agent (HTTP header) to achieve the same effect.
|
|
### Alternative Syntax Highlighting
|
|
Apart from the default shiki for highlighting, You can use [Prism](https://prismjs.com/) as code highlighting engine, see [Syntax Highlighting in Astro Docs](https://docs.astro.build/en/guides/syntax-highlighting/#add-a-prism-stylesheet) for details.
|
|
|
|
To simply add features like code copying over the default Shiki formatter, you can simply import the `src/components/CodeScript.astro` to the Layout.
|
|
|
|
You can also use [Expressive Code](https://expressive-code.com/) to get features like code copying over the syntax highlighting:
|
|
> Warning: Expressive Code will load JavaScript by default. This will not follow your `noClientJavaScript` settings.
|
|
|
|
1. Install Expressive Code:
|
|
```shell
|
|
pnpm astro add astro-expressive-code
|
|
```
|
|
You can answer all Yes to prompts as we will modify the config later.
|
|
2. Edit `astro.config.mjs`:
|
|
```diff
|
|
- integrations: [sitemap(), mdx(), partytown(), expressiveCode()],
|
|
+ integrations: [sitemap(), expressiveCode(), mdx(), partytown()],
|
|
```
|
|
3. Create `ec.config.mjs` in the project root and adjust the config to your liking. To make things easier you can use [this config file used by the author](https://raw.githubusercontent.com/BlockG-ws/gb-lab/refs/heads/master/ec.config.mjs)
|
|
|
|
## 👀 Want to learn more?
|
|
|
|
See the post [🕊](). I hope you like it. 💜
|
|
|
|
## 😊 Special Thanks
|
|
The terminal theme from [bearblog](https://bearblog.dev) is cool, and it inspired me to create a theme like this.
|
|
|
|
[Bolt](https://bolt.new) by StackBlitz (anyway I'm not affiliated with them) helps me to create a starter template from screenshot when I don't know where to start, the one now is much different from the template though.
|
|
|
|
Other tools like GitHub Copilot helps too.
|
|
|
|
(I know the LLMs sometimes sucks, but it really helps most of the time)
|
|
|
|
Also, [delucis/astro-blog-full-text-rss](https://github.com/delucis/astro-blog-full-text-rss) for implementing full text RSS in pretty easy way.
|
|
## ⚖️ License
|
|
GNU Affero Public License 3.0 |