Hacker News Reader

Comment by enriquto | Hacker News Reader

I never understood the purpose of those "static page generators". The only thing they really do is add a html header to your text? Honestly, for all that hassle I prefer to copy-paste manually a few lines of html every time that I write a new file, and that's it.

View on HN

They do add stuff - that's the point, but limiting it to HTML boilerplate isn't all.

My static generator:

* Renders boilerplate

* Builds the correct file paths

* Generates a JSON tree for a clientside search engine

* Generates a RSS feed

* Creates a global navigation menu

* Examines all my code blocks, and if they're valid, also renders output into the finished file

* Spelling and grammar checks my pages

I could do all that manually, but it'd be a pain and take a lot longer.

Out of curiosity, which static page generator is this? I'm especially interested in generating JSON for clientside search, freeing me from linking to Google...

Jekyll: https://techtales.rocks/

Not OP, but it's on their profile.

That's just what's up for now. I'm in the middle of rebuilding one I wrote around Pandoc, so I tossed Jekyll up for now, though Jekyll is capable of everything I described, I just don't like its way of doing things.

One I'm writing myself, but generating JSON for clientside search is actually fairly simple with most generators.

Like this quick and easy Jekyll article [0][1].

It all kinda depends how detailed you need your search engine to be. Fuzzy matching requires a little bit more JS. My go-to is lunr.js [2] to take care of all of that for me.

But basically all you need is a page that can iterate over all other pages that exist, (like a TOC would), and that can plug on the data into your search function for you.

[0] http://mathayward.com/jekyll-search/

[1] https://github.com/mathaywarduk/jekyll-search

[2] https://lunrjs.com/docs/index.html

Jekyll also makes use of Liquid (https://shopify.github.io/liquid/) which works great for auto generating page content. As an example I setup a simple one page Jekyll site that has a liquid script that automatically embeds in alphabetical order all images found in a folder.

I prefer writing markdown to html.

I want an automatic table of contents.

Source code highlighting is nice too.

I use mdbook and not Jekyll anymore, but it's similar stuff.

> I prefer writing markdown to html.

Really? Well, this is just personal preference. I actually find html clearer for very simple documents. There are so many different markdown flavors that it is in practice rather ambiguous. You cannot easily copy markdown text from one conntext to another. For html, it is much easier.

> I want an automatic table of contents.

That's a really good reason, and probably the only reason that i can imagine to use generators.

> Source code highlighting is nice too.

I have been beaten not once, not twice, but three times by silent changes in jekyll setups that changed the rendering of my code (so everything looked really bad, with negative red blocks, etc). I hated this so much, and was so enraged, that I converted all my documents to pure html and now I am much happier. The reasons for the changes that broke my pages were completely banal ones, like moving from pygments to ruby-whatever (or vice-versa), etc.

> There are so many different markdown flavors that it is in practice rather ambiguous.

Just use ones that follow http://commonmark.org/ They should render the same.

the problem is not so much the markdown itself, but the variety of plugins. In practice, a simple "apt-get upgrade" may break markdown rendering.

The nice thing about generators IMO is that when you want to change something on every page (a simple example being a <meta> tag or the page heading) you just have to update the template and run the script, instead of updating every file.

I don't really love Jekyll either, that's why I have my own generator written in Node, and my dependencies are defined strictly in my package.json to keep things like markdown parsing from breaking.

Heck, generators can just be a sh script with some sed commands.

and footer and sidebar and other 'components'.

They do much more: primarily, they translate from markdown to HTML. This is, you don't write your content in HTML, you write it in a markup language that the static generator converts in an HTML document. Then, they can manage tags, paginating, menu structures, etc.

For instance, you can write

> {% note %} Something I want to emphasize {% endnote %}

And this will be converted by the generator into a properly-styled <div> according to your theme. If you change the theme, another run of the generator will convert the note to a different style, without you needing to change your content.

but that's exactly the purpose of HTML and CSS

      an <em> emphasized </em> word

and then you style the tag however you want. You just change the .css file, no need to rerun anything.

In that example yes, but if I put {% author %} Name {% author %}, a static build system can put the author name centered in the top of the page, or in a signature at the bottom, or in a floating div on the sidebar, or...

In your HTML document, you would need to change the structure manually for each content file, of which you can have thousands.

I understand. However, in the rare cases I have to make global changes, I prefer to write a throwaway awk program that does the job automatically.

...and then update the sidebar in 15 places when adding a new entry...

A static site generator lets you only update it in once place, rather than 15, when you make a change.

Not to mention creating pages for all my tags.

Static site generator (Hugo) plus my ox-hugo (Emacs/Org mode) plugin allows creating this whole site[0] from a single content file :)

[0]: https://ox-hugo.netlify.com

Reply on news.ycombinator.com