Official website engine

[ai]

We need an engine for new website. Requirements:

1. Have plain HTML file for every page in dist/ folder
2. No hydration or big JS files. We may have JS only for simple things like framework switcher.
3. No analytics or collective any private data. Only how many users visited website.
4. Simple build tools even with a lack of DX. We need to reduce dependencies to be able to update the project a few years later.
5. Simple deploy. I am thinking of using Github Pages (they are very stable).
6. Some tool to generate beautiful pages from TSDoc.

The input to website:

1. Markdown files
2. .d.ts files
3. HTML for layout, JS and CSS styles
4. Assets like favicon.ico

I want, also, to re-use some tools from another website which I support:

1. Prettier. ESLint and Stylelint with Logux’s configs.
2. pnpm
3. asdf for Node.js and pnpm versions control

[Doodidan]

Hello.

Recently I was looking for simple engine for my blog to create website from .md[x] files. I tried gatsby, nextjs and jekyll and I stopped at the last one. I want to share some thoughts about it.

Gatsby:

• - it goes with reactjs
• - it's hard to get frontmatter data into page template
• + it's easy to setup

Nextjs:

• - it goes with reactjs
• - hydration, react server components
• - poor mdx support in new 'app directory' architecture (example)
• +- it's good and stable in old architecture but not all needed features are supported (example)
• + very flexible

Jekyll:

• - not JS ecosystem but Ruby so it does not hit all your requirements like pnpm and asdf
• + flexible
• + good frontmatter support
• + plain HTML and CSS
• + beautiful support for Gitgub Actions (GHA works with Jekyll in core)
• ? IDK about .d.ts and TSDoc support

I can recommend Jekyll.

Also this topic is interesting for me so I will subscribe and I will be glad to have a discussion.

[ai]

I am thinking of writing small script to compile Markdown and add layout and use Vite to compile assets.

It looks like a better future-proof version, since require less time to maintain and update.

And anyway we need this option for TSDoc.

[daguttt]

What about Astro ?

[ai]

@daguttt it is important to select solution based on requirements, not on trends.

So we need an explanation how it fits the requirements and why it is better than anything else.

[blikblum]

I recommend astro.

Have plain HTML file for every page in dist/ folder

Check. By default no JS in client side. If you need JS is possible to add React or Svelte or Vue

No hydration or big JS files. We may have JS only for simple things like framework switcher.

Check

No analytics or collective any private data. Only how many users visited website.

Check

Simple build tools even with a lack of DX. We need to reduce dependencies to be able to update the project a few years later.

Uses vite under the hood that has no sign of development stale

Simple deploy. I am thinking of using Github Pages (they are very stable).

https://docs.astro.build/en/guides/deploy/github/

Some tool to generate beautiful pages from TSDoc.

Out of box there's not. But since astro can render markdown, just convert tsdoc/typedoc to markdown (there are a few tools) or even directly to html

Bonus: supports nanostores: https://docs.astro.build/en/core-concepts/sharing-state/#why-nano-stores
They have a simple docs starter: https://astro.build/themes/details/docs/ (i added doc to my project easily using it)

A new theme was added recently after last time i looked: https://astro.build/themes/details/manual/

[ai]

Simple build tools even with a lack of DX. We need to reduce dependencies to be able to update the project a few years later.

Uses vite under the hood that has no sign of development stale

Does Astro a single-page-app framework? Having SPA framework (React/Svelte) and then add complex SSR is not a simple solution compare to hanging a simple HTML page template.

[daguttt]

@ai Astro is primarily a SSG framework. So is plain HTML by default

[blikblum]

It uses vite as dev server .

You may want to look at how it handles the optional JS / frameworks: https://docs.astro.build/en/concepts/islands/

[ai]

@daguttt @blikblum what features will we have by using Astro instead of just Vite (and simple scripts to compile Markdown and TSDoc)? We do not need islands for instance.

[blikblum]

IMO is better have a dedicated / proved tool than try to (re) create an alternative. In the end is less code to maintain, faster shipping

[ai]

@blikblum it works only if existed tools fit your case. As I understand Astro is not fitting our case, because it was created for applications, with islands, etc. As the result, it is overcomplecated for our case and overcomplecated solutions is always hard to support.

We did this mistake for postcss.org and it took days of my life for update tool on major releases (before I re-wrote it to custom script).

Let’s check alternative. Trend-based solution choosing is bad (did we start of thinking of Astro because it was perfect for our case or just because it is popular and you like it?).

[blikblum]

Its the contrary. Astro is by default HTML only so it fits the requirements. The islands is a scape hatch for interactive usage. Using islands is opt in. Not opt out: https://docs.astro.build/en/concepts/mpa-vs-spa/

I was think a bit about using vite + markdown script: vite is primarily for SPA. I even dont know if it would work without a bit of javascript

I used Astro in two sites. Basically i just create standard markdown files. It spits html file without JS at all.

But in the end is your call

[cravend]

Hi, just wanted to chime in on this — I actually found out about nanostores through Astro (https://docs.astro.build/en/core-concepts/sharing-state/).

I'm using Astro to re-create my personal website, and I can second this statement:

Its the contrary. Astro is by default HTML only so it fits the requirements. The islands is a scape hatch for interactive usage. Using islands is opt in. Not opt out: https://docs.astro.build/en/concepts/mpa-vs-spa/

For what was described above, I see no reason to use the Islands features of Astro (or even React) — you can just write plain HTML/CSS and markdown and it will convert it into a set of HTML pages, with no JavaScript.

[markpinero]

I was an early adopter of Astro in beta and am currently using it on production in many projects (e-commerce, landing pages) and will concur with @ai that in his use-case, it may not be the right tool. From a dependency perspective, Astro is large and a lot of the magic may not be wanted (automatic css scoping, script hoisting).

I would consider Eleventy to be a good base for these requirements.

[j]

I wanted to leave this here. I also would have never used nanostores had it been for Astro.

They recently announced documentation building framework:

https://github.com/withastro/starlight

[ai]

Just found TypeDoc integration for Starlight

https://github.com/HiDeoo/starlight-typedoc

[droganov]

Just an idea, i've been making md notes for my homepage and came up to using Obsidian. And even made a small setup with nextjs13. So far this integration looks very promising for static webites. nextjs can be repleced with whatever, the Obsidian was the big find.

[btakita]

Its the contrary. Astro is by default HTML only so it fits the requirements. The islands is a scape hatch for interactive usage. Using islands is opt in. Not opt out: https://docs.astro.build/en/concepts/mpa-vs-spa/

I use nanostores + solid.js (along with ctx-core) primarily using SSR with a simple bespoke hydration api to load interactive components on an Astro MPA. In other words, a simple custom "islands" implementation without the general purpose hydration bloat that comes with the isomorphic component libraries. They present a fantastic usage of customElements to hydrate data & initialize component bindings. Their client side <script> tag & import resolution generates focused client-side bundles using vite/esbuild. Have to say it's close to ideal for my use cases.

nanostores is a superb way to integrate state between the islands, which is probably why Astro recommends nanostores. Yes, I was also introduced to nanostores via Astro.