51–60 of 64 posts
I'm currently using Material for MkDocs but was thinking of switching off it, in part due to the lack of options around having custom highlighting in code blocks (my docs website is for a programming language I am working on). What are Zensical's plans here? Tree sitter highlighting would be perfect in my case.
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.
Creator of Zensical here! As always, it's a matter of taste. We felt the original look was a little date. You can use the classic Material for MkDocs look with Zensical by adding a single line of configuration[1]. This works because the HTML is exactly the same right now. Most users favor the new look over the old one. [1]: https://zensical.org/docs/setup/basics/#theme-variant
This looks great! I'm currently using Material for MkDocs but was thinking of switching off it, in part due to the lack of options around having custom highlighting in code blocks (my docs website is for a programming language I am working on). What are Zensical's plans here? Tree sitter highlighting would be perfect in my case.
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?
If Material for MkDocs ticks off all or most of the boxes, you can definitely start using it, and switch later once everything you need is available. Our promise to the 70k+ projects using Material for MkDocs is that we'll make switching to Zensical as simple as possible with automatic conversion tooling once we ship certain functionality. The compatibility we have now is a first step towards that goal.
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…
I would be interested to know why the radical change to move the configuration file from YAML to TOML. Is there any good reason for that change?
[1]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-py...
I would be interested to know why the radical change to move the configuration file from YAML to TOML. Is there any good reason for that change?
Zensical team here. Yes, there are very good reasons for that change. First and foremost, with MkDocs using YAML, and Material for MkDocs being the main entrypoint for many of our users, we got a lot of issues with users having trouble just getting the indentation of YAML right. Secondly, and this is even more problematic: Python Markdown allows the use of custom YAML tags[1], which translate to function references d…
Since adopting it, I’ve also grown fond of Mike, the plugin which lets users see the various different versions of a doc (without needing to resort to git).
But I’ve also experienced plenty of pain points when pushing the customisation envelop. Weird bugs appeared in many places which were clearly due to MKDocs’s poor architecture and performance was also never stellar.
Congratulations on launching Zeniscal and I’m quite excited to see the future of it, but I do very much hope that in 12 months time, one way or the other, I’m able to still have similar functionality to what the plugins provide.
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…
While it is great for documentation, we used it for the whole website of a project, mainly because people in the team already understood it. But we ran into many issues when it came to adding a blog...
Sphinx has a hard requirement for input files to be on disk. It means that, for example, it would be hard to add a page that lists all blog posts posted in a certain category (as the "meta" page would have to inspect other pages and then be generated on the fly). The only option is to pre-generate such pages into the source folder before a build.
I think that the inputs should be abstracted in a way such that there isn't a hard requirement on the filesystem. For example, extensions should be able to add input files using code, without having to write them to the filesystem first. This would make many things much easier and open a new world of possibilities without actually resulting in more maintenance work for the ssg.
The thing is that the output is abstracted in that way, one can create a new plugin to write to a different output format. If one could also "generate" input/source files dynamically, one would get support for all of these output formats "for free".
As for me personally, I don't really have enough blog posts to have to store them in a db, that was just an example. But if abstracted transparently in the way I am thinking about it actually doesn't matter for the ssg, it only knows about inputs and outputs and not how it got these inputs.
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 aw…