Show HN: Clayoven – beautiful website generator aimed at math-heavy sites | Hacker News Reader

Show HN: Clayoven – beautiful website generator aimed at math-heavy sites

github.com

115 pointsartagnon26 comments

The adjective 'beautiful' for software is increasingly becoming a turn-off for me. Perhaps with the exception of Sublime Text, there is no software that I routinely use for its pleasing aesthetics. I'm more interested in fast, intuitive, pragmatic software. Beautiful makes me thing that other, more important things have been given lower priority.

What exactly makes Clayoven beautiful? It seems to have a great niche purpose. Shouldn't the first adjective be something related to what math users would value?

Yes, it's not the fastest ssg; there's Zola for that. However, digging git history with `git log --follow` can take a moment, and the MathJaX server-side rendering takes 10 seconds on a math-heavy site. However, incremental builds are the default, and a full-rebuild is seldom necessary. What makes it beautiful is the following:

1. You don't have a metadata header, like in most SSGs; timestamp is picked out from git-history, and topics/subtopics is simply picked out from the folder structure.

2. The syntax is terse, and features like un-numbered lists is excluded on purpose, because mathematicians like to number or letter everything.

3. The implementation of claytext is simple. There is no complicated markdown-processing, and even hard-wrapped lines are not allowed.

4. There's a dedicated vscode extension for auto-completing MathJaX. It also triggers a build-on-save, so you can just save changes in vscode and refresh the browser to see the changes.

5. Server-side rendering of math, so that the client isn't burdened with executing heavy javascript. It actually uses a custom fork of XyJaX to achieve this for commutative diagrams.

Websites are largely a visual medium so when you use the word beautiful most people are going to assume you're describing the visual aspects of the sites the tool generates, not the tool itself. And I get that beauty is subjective, but when you give terseness and arbitrary lack of features such as unnumbered lists as reasons for why it's beautiful, it's a little strange.

Beauty being subjective, it’s best left to others to describe the project as beautiful rather than the author. Like the difference between someone saying “I’m beautiful” vs having someone else describe them as beautiful, that comes across as a lack of humility in most contexts no matter how true it is. I think that may be why so many here including myself find it off-putting.

Yeah, besides beauty being quite subjective, mentioning beauty as the primary differentiator gives the impression that utility is less of a focus. In today’s environment where there’s an abundance of new software lacking depth and maturity, promoting the “beauty” (whatever that is) of a product is more often an indicator of just that.

> Shouldn't the first adjective be something related to what math users would value?

“Beauty” is very important to mathematicians. Check out the Wikipedia article on the subject:

https://en.m.wikipedia.org/wiki/Mathematical_beauty

but not this kind of beauty. first sentence of the linked wiki

>Mathematical beauty is the aesthetic pleasure typically derived from the abstractness, purity, simplicity, depth or orderliness of mathematics.

not of the type setting of mathematics (that's just regular plain old aesthetical beauty).

perhaps more relevant is how knuth literally took a decade off from writing his books to write a better typesetting system.

I think it is okay in this instance as it relates to an output generator (and beautiful output should be a key functionality of such a tool)

The problem is hyperbole. "Handsome" or "highly-readable" would be more apt.

Looking at the blog post on linear algebra, the line spacing seems a bit jammed in the presence of the inlined math.

> What exactly makes Clayoven beautiful?

It's written by a Ruby dev? :P

Indeed, one does not see open source java projects self promoting as “beautiful”, nor many others languages (Python jinga?). Reasonable to assert the Use/misuse of the adjective based on that imo.

Doesn’t look very carefully crafted for something they claim to be “beautiful”.

> There is no published gem. To get started, clone, run bundle to install the required gems, and put bin/clayoven in $PATH.

Yuck? Is it so difficult to package and publish a gem these days? Did the author not find time to do so in the years they’ve been working on this project?

> To start writing, install vsclay for vscode, which will provide the necessary syntax highlighting, IntelliSense support for MathJaX, and trigger-[incremental build]-on-save functionality.

What about integration with other editors? Will my “beautiful” experience be ruined if I happen not to use vscode?

Definitely looks like a very “scratching my own itch” kind of project - worth sharing but the adjective used to present it sounds like an overstatement.

I’ve been much happier using KaTeX over MathJax. Indeed KaTeX can actually be rendered server-side. This prevents an ugly flash of unstyled content on math-heavy pages.

KaTeX doesn't do commutative diagrams, unfortunately.

Have you tried MathJax 3? I found the render speed was the same recently.

The marketing text in the readme is more self congratulatory than useful to the end user. It’s fine to be proud of one’s work, but the documentation should first consider the needs of the project’s consumers. If it were up to me I’d strip out all the nonsense about the beauty of the code—at the end of the day, it needs to run well. Whatever clever or minimal techniques or linter rules you think make the code beautiful are not relevant to anyone that’s not a contributor to the code base.

The demo doesn’t look particularly beautiful. Not that it’s bad but just not what I would think based on the marketing.

Neat project! Beauty feels like an under-explored part of programming. It's neat to see how a language can be designed to be more expressive for a particular use case. I wouldn't make a call to use a piece of tech at work just for beauty but I certainly do that all the time in my personal projects.

Am I reading something wrong? I thought they meant it outputs beautiful websites, whereas your comment seems to imply that it's the code/(library api) that's beautiful.

Outputting beautiful designs is a function of the css, no? The bundled css is quite minimalist, and it comes packaged with a relatively simple starter website.

I also thought you meant the output was beautiful and thought it was strange that there was no demo or example showing it.

I made something similar with KaTeX and Markdown. Mine is plain.

Demo: https://timdaub.github.io/SSRP/

Source: https://github.com/TimDaub/ssrp

I went with Org-mode and KaTeX, unfortunately there's a bug with Org-mode where it doesn't insert the trailing space after inline LaTeX. I never got around to fixing it. I did try to make mine "beautiful" or at least pleasing to myself.

Demo: https://eddieh.github.io/stix-org/

Code: https://github.com/eddieh/stix-org

I use Marker[0] markdown editor, which has built-in support for MathJax and KaTex for math, and Jekyll, to render my blog to GitHub.

[0]: https://github.com/fabiocolacio/Marker .

Reply on news.ycombinator.com