Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Zensical – A modern static site generator built by the Material for MkDocs team

squidfunk.github.io

Post reply on HN
Print view View original

41–50 of 64 posts

Re: Zensical – A modern static site generator built by the Material for MkDocs team

#41

Post by perpil »

sureglymop wrote: post #40

Can I also use it to write blog posts and generate an RSS feed for them? A lot of documentation sites want this but it was always hard with things like sphinx where the input must be files on disk so one couldn't e.g. load blog posts from a db.

Its predecessor (mkdocs material) supported blogs via a plugin and rss feeds via a mkdocs plugin (https://guts.github.io/mkdocs-rss-plugin/). I don't believe it supports blogs yet according to this: https://zensical.org/compatibility/#phased-transition-strate... but will in the next phase when it supports plugins.

It doesn't support loading content from a database that I'm aware of, it uses markdown files on disk as input.

Re: Zensical – A modern static site generator built by the Material for MkDocs team

#42

Post by j1elo »

quietbritishjim wrote: post #39
fishgoesblub wrote: post #2

I was excited up until they showed what the new theme looks like. mkdocs-Material was nice in that it didn't have overly rounded corners and over travesties, a shame that custom CSS will be needed to undo the "modernisation". Overall this seems very interesting, especially the performance improvements, just a letdown visually.

Someone builds a complete documentation system from scratch and you call it a "travesty" because it has rounded corners ? Visual design is important but this is very misplaced priorities.

In todays News, someone built a whole Hotel with freely available design plans, and a user finds a travesty in the font style of the Cold/Hot sink taps being too round.

Re: Zensical – A modern static site generator built by the Material for MkDocs team

#43

Post by finallyspeaking »

I’m delighted to see this project evolving and look forward to following its development! I’ve used just about every markup technology over my (many) years as a tech writer, from troff macros, to SGML/DocBook and then XML/DITA, and finally, to Markup with the Material for MkDocs project, as a sponsor. Each has its strengths and weaknesses, but for enabling contributors outside the tech writing community, simpler source formats are the way.

That said, if pressed, I’d recommend AsciiDoc[0] over any Markup flavor for a greenfield project _today_. We had to either add or bake plugins or extensions to get features that are already included in AsciiDoc, making our Markup implementation both more complex and wholly unique. That wasn’t a huge problem, because we didn’t have a large pool of contributors to educate and support, but it would have been much easier just to point to a standard.

But, hey! The roadmap includes modules, to make way for other source formats! This is the way. :-)

[0] https://asciidoc.org/

EDIT: s/That's the way/This is the way. :-)/

Re: Zensical – A modern static site generator built by the Material for MkDocs team

#44

Post by sureglymop »

perpil wrote: post #41
sureglymop wrote: post #40

Can I also use it to write blog posts and generate an RSS feed for them? A lot of documentation sites want this but it was always hard with things like sphinx where the input must be files on disk so one couldn't e.g. load blog posts from a db.

Its predecessor (mkdocs material) supported blogs via a plugin and rss feeds via a mkdocs plugin ( https://guts.github.io/mkdocs-rss-plugin/ ). I don't believe it supports blogs yet according to this: https://zensical.org/compatibility/#phased-transition-strate... but will in the next phase when it supports plugins. It doesn't support loading content from a database that I'm aware of, it uses markdown files on disk a…

Thanks for the information. If files on disk are a requirement that would be a shame. Such tools keep abstracting such that one can generate a plethora of output formats but don't abstract the input in such a way that one could programmatically add content. Even though that wouldn't stand in the way of using the filesystem as the source regardless.

Re: Zensical – A modern static site generator built by the Material for MkDocs team

#45

Post by parser_error »

This looks very interesting, I'm using mkdocs+material for one site (and it's great) but trying to find a good solution for more complex docs.

Is there anything planned like 11ty's data files[1]? For example, I can pass it a JSON file, or a TOML file, and have it generate one HTML page per document in that file using their pagination system in a hacky way, and add those pages to collections for grouping in navigation and such using their templating language. This makes it a lot easier to autogenerate documentation from a combination of sources (since anything we want can emit some appropriate JSON/TOML) without having a real "source document". It's hard to tell at a glance if this is something that would be possible with the upcoming module system.

[1]: https://www.11ty.dev/docs/data-global/

Re: Zensical – A modern static site generator built by the Material for MkDocs team

#46

Post by mroche »

finallyspeaking wrote: post #43

I’m delighted to see this project evolving and look forward to following its development! I’ve used just about every markup technology over my (many) years as a tech writer, from troff macros, to SGML/DocBook and then XML/DITA, and finally, to Markup with the Material for MkDocs project, as a sponsor. Each has its strengths and weaknesses, but for enabling contributors outside the tech writing community, simpler sour…

> That said, if pressed, I’d recommend AsciiDoc over any Markup flavor for a greenfield project _today_.

Likewise for me as well, and I am a massive Material for MkDocs fan. Markdown is certainly simple to use and gets the job done, but AsciiDoc just provides so much out of the box without hurting my eyes like reStructuredText (used by Sphinx) does. It also helps that's there's effectively one type of AsciiDoc I'm aware of, whereas there's a number of Markdown flavors atop CommonMark to be cognizant of. I will concede, however, it's learning curve is not as simple as MarkDown's...

A powerful framework for working with AsciiDoc for documentation purposes is Antora[0]. The Red Hat ecosystem (Fedora and CentOS projects) uses it for their public facing docs. That being said, it is a beast to understand if starting from scratch rather than contributing to project's existing docs. It designed to be able to consolidate large projects with multiple component repositories and versions per component into a single docs site. Typical balance of more capabilities, more up-front cost of adoption.

The AsciiDoc WG also maintains an Awesome AsciiDoc[1] page of projects within the ecosystem.

[0] https://antora.org/

[1] https://gitlab.eclipse.org/eclipse-wg/asciidoc-wg/asciidoc.o...

Re: Zensical – A modern static site generator built by the Material for MkDocs team

#48

Post by adastra22 »

How mature is this right now? I am just now starting a new greenfield project and might have gone with MkDocs. Should I do Zensical instead? Or would it be better to use Material for MkDocs while the bugs are being worked out, and trust in the upgrade path?

Re: Zensical – A modern static site generator built by the Material for MkDocs team

#49

Post by adastra22 »

whycome wrote: post #30
squidfunk wrote: post #13

Earlier quoted context omitted.

From the feedback we got after launching. More accurately: most users that we conversed with since launch are very happy about the new look. Regardless, for compatibility reasons, the old look is available as well.

Early adopters are a very distinct set of users. Probably not great to extrapolate from it.

If you are expecting your market share to grow, then new users will outnumber existing users and it might be wise to extrapolate.

Re: Zensical – A modern static site generator built by the Material for MkDocs team

#50

Post by jarofgreen »

sureglymop wrote: post #40

Can I also use it to write blog posts and generate an RSS feed for them? A lot of documentation sites want this but it was always hard with things like sphinx where the input must be files on disk so one couldn't e.g. load blog posts from a db.

> load blog posts from a db

Can you explain a bit more about your requirement and how many blog posts you are talking about?

I'm curious to hear more for my future work as I have an extendable static site builder it would be easy to add this too. I don't want to be going all marketing on someone else's post (and it's early days so you'd probably find other features lacking) so I'll just say my email is in my profile if you want.

Post reply on HN