Mercury

Terminal-like blog theme built from Astro, still in early beta.

Demo: https://icy-beach-00f5be01e.6.azurestaticapps.net/

🧑‍🚀 Seasoned astronaut? Delete this file. Have fun!

NOTE: We are migrating to Astro 6! The older version, which will be live on astro-5 branch, may not support all features listed below.

🌌 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:

git clone https://git.gb0.dev/gb/mercury.git

cd mercury && pnpm install

NOTE: if you had issues when installing dependencies, try to add SHARP_IGNORE_GLOBAL_LIBVIPS=true to avoid sharp from building from source.

run the dev server:

pnpm run dev

open 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

• Initial project setup
• Basic theme implementation
• Better full-text search without Fuse.js
• A mode to make the site 0 JavaScript
• Multiple authors via YAML
• i18n support
  • UI text
    • Support more languages (help needed!)
  • Localized content
    • Alternative structure like Hugo's index.[lang].md
  • Translations
    • Better language switcher
• Better support for printing version
• Add support for more comment engines
• Multiple comment engines in the same page
• Add support for umami statics
• Improve documentation
• Bump to Astro 6
• 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

activitypub support

There is an ongoing work to implement it on lab ran by the author based on Astro DB and fedify. Once it's done, the instructions will be updated here.

i18n

i18n support for UI text and content translations are implemented, but the language switcher may be broken for some pages.

To implement i18n, you should:

1. (Recommended) Move existing content to src/content/posts/[default locale]/. (This is not required, but can make things easier)
2. Create a new folder under src/content/posts/ with the language code as the name (e.g., en, zh-CN, etc.).
3. Add your translated Markdown files into the new folder.
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:

    @no_html {
        # Match if Accept header does NOT contain text/html
        not header_regexp Accept (?i)text/html
        # Match the path and capture the blog slug
        path_regexp text ^/blog/(.*)$
    }
    
    # Handle the matched request
    handle @no_html {
        # Use the capture group from the 'text' path_regexp
        rewrite /blog/{re.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.uri.path matches "^/blog/.*" and not any(http.request.headers["accept"][*] contains "text/html"))
   

   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 as code highlighting engine, see Syntax Highlighting in Astro Docs 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 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:

   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:

   - 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

👀 Want to learn more?

See the post 🕊. I hope you like it. 💜

😊 Special Thanks

The terminal theme from bearblog is cool, and it inspired me to create a theme like this.

Bolt 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 for implementing full text RSS in pretty easy way.

⚖️ License

GNU Affero Public License 3.0