1. 52
  1.  

  2. 17

    Using a static site generator means that you have to keep track of two sources: the actual Markdown source and the resulting HTML source.

    This is not representative of my experience. I can delete my generated /public folder and re-run Hugo again to generate a new site. I only have to keep track of my source.

    Finally, you constantly have to work around the limitations of your static site generator.

    This is very true. I use Hugo, and it changes very fast, often breaking some things. Also, it started out as a blog site generator, and adding features to make it a generic site generator has required paying attention to releases and updating my custom theme to prevent my site from breaking.

    But how can I then keep the style and layout of all my posts and pages in sync?

    I actually think this is kind of neat. I like the idea of a web of interconnected pages each similar but a little different, evolving over time. It reminds me of the old web.

    🤔 I should redesign my website.

    1. 6

      Hugo is dang frustrating. Recently I accidentally updated it from the distro, jumping ahead 15 versions. At some point they made pygments go from rendering my site in <100ms to rendering in 15s. Then I tried switching to Chroma, but it turns out there’s no extension system, so to tweak my code highlighters I needed to manually compile Chroma and then manually compile Hugo.

      Then I found out that you use a tweet shortcode, you can’t preview your site offline. That broke me and I went back to a 2016 build.

      1. 1

        I feel you. That is why I use specific versions of hugo for my site, not one supplied by a distro.

        Also I recommend using hljs. I like it (progressive enhancement) better than the pygments. I’ve had some problems with pygments in the past, but I cannot recall it. (Also had some minor annoyances with hljs, but I’m generally OK with it).

        Regarding the tweet shortcode… I never used that (I prefer screenshots of tweets and links, as I do not trust linking third party sources. They can change/disappear, and it would ruin my point). Could you link an issue or something so I could understand it? It made me curious.

        1. 1

          Yeah, I think I’ve been lucky in that not much has broken for me.

          The biggest issue I ran into a couple of months ago was a change that prevent me from using a / in a tag name to fake sub-paths. I used this to match my old URL schema from before I was using Hugo.

          Hugo removed (”“fixed””) the tag issue, so I updated my blog to use another solution, BUT then Hugo reverted the change. Ha!

        2. 4

          I used to write my blog (for the past 19 years) in raw HTML. Then a few months ago I implemented my own markup language (based upon Orgmode with a lot of extensions for how I write posts), but I still only keep the rendered HTML, not the original source. That way, I’m not stuck with supporting outdated versions of my markup formatter.

          1. 2

            This is not representative of my experience. I can delete my generated /public folder and re-run Hugo again to generate a new site. I only have to keep track of my source.

            But even then, you must keep both the source and the result in your head, because you have to worry about how your Markdown will be translated to HTML (dependent on the version and implementation of Markdown) and how your posts will be arranged in public/.

            This is very true. I use Hugo, and it changes very fast, often breaking some things. Also, it started out as a blog site generator, and adding features to make it a generic site generator has required paying attention to releases and updating my custom theme to prevent my site from breaking.

            This is a great summary of the problem! Websites created with static site generators are quite fragile.

            1. 4

              But even then, you must keep both the source and the result in your head, because you have to worry about how your Markdown will be translated to HTML (dependent on the version and implementation of Markdown) and how your posts will be arranged in public/.

              I’m still not aligned with you on this. I do have to think about my HTML when I am building my custom theme, not when I’m building the site or uploading it.

              The only thing I have to consider when creating new content is where my feature image is located and use the correct path in my content’s meta data. The thumbnails and their use in the page are auto-generate, and the content is put where it needs to be, and related links menu items and homepages are all updated per my theme.

              1. 1

                I suppose it depends on what type of content you write, but I find it hard to maintain things like footnotes and tables across different implementations of Markdown and static site generators (or even the same generator but a different version). Not to mention things like elements with custom classes and inline HTML.

                What I mean is, if you’re writing HTML directly you always know what the resulting HTML will be. If you write in Markdown, you always have to spend time thinking about what the HTML will look like. You usually have a good enough idea, but you could be wrong.

                1. 1

                  What I mean is, if you’re writing HTML directly you always know what the resulting HTML will be. If you write in Markdown, you always have to spend time thinking about what the HTML will look like.

                  I think this is why I hate ORMs. Instead of just writing the SQL I want, I have to learn how to express it in whatever weird interface the library exposes – assuming it’s even expressive enough.

                  1. 1

                    Is Markdown really in that much of a state of flux?

                    I’m using the OG Daring Fireball edition, I do know that there’s been some work to integrate stuff like footnotes and ToC (which Gruber opposed on philosophical grounds). It’s been frozen since… 2011? 2004

                    I’d rather use a tool that made it easier for me to write a blog post every day (let’s face it, every month more like it) than worry about future incompatibility in the HTML rendering tool I’m using.

                    1. 1

                      Is Markdown really in that much of a state of flux?

                      Not Gruber’s Markdown, but yes, certainly if you’re switching between implementations (or versions thereof) or static site generators (or versions thereof) that use different implementations.

                      I’d rather use a tool that made it easier for me to write a blog post every day (let’s face it, every month more like it) than worry about future incompatibility in the HTML rendering tool I’m using.

                      Indeed – that’s exactly how I feel writing posts in HTML. Nothing can go wrong, no matter what system I’m using or what programs I have installed.

                2. 2

                  Websites created with static site generators are quite fragile.

                  Only if the site generator ever changes. I use one written in Clojure that has not been changed in years.

                  1. 1

                    That is why I made my own. A few lines of Python and your ready.

                  2. 1

                    I actually think this is kind of neat. I like the idea of a web of interconnected pages each similar but a little different, evolving over time. It reminds me of the old web.

                    🤔 I should redesign my website.

                    This cracked me the hell up :D

                  3. 16

                    One benefit of using a CMS or site generator is an automatic RSS feed. Hint: this blog currently has no RSS feed ;)

                    1. 5

                      I was really considering writing a blog that actually uses an RSS feed as the source of truth, then uses XSLT to generate the HTML…

                      1. 6

                        Pro tip: use an Atom feed. RSS 2.0 is pretty loose, spec wise.

                        1. 1

                          This brings back old memories. Back in 2006, I think, I used a CMS called Symphony that would generate XML and then you’d style your blog using XSLT. Since I was a junior developer back then, it was quite handy to learn XML and XSLT, which were still the rage back then :-)

                        2. 2

                          That is very true, but I’m working on a shell script to generate a feed from HTML.

                          Edit: Here’s a preliminary version of the script (results).

                          1. 3

                            Be careful your shell script doesn’t turn into a static site generator!

                            1. 1

                              Indeed! I saw it coming too, so now I’ve switched to a PHP script (feed.php) that generates it on the server from my index.html, so that I don’t have to worry about generating it :-)

                        3. 12

                          This appeals to me. However:

                          But how can I then keep the style and layout of all my posts and pages in sync? Simple: don’t! It’s more fun that way. Look at this website: if you read any previous blog post, you’ll notice that they have a different stylesheet. This is because they were written at different times. As such, they’re like time capsules.

                          While that’s kind of cool in its own way, I don’t prefer it. Especially when it comes to a site menu.

                          My first web sites were hand-coded HTML. My motivation to learn PHP was that I wanted a consistent menu across all pages, and copy-paste was not maintainable, so I landed on PHP’s include. From there it was down the rabbit hole to becoming a web developer.

                          I use a static site generator now for nathanmlong.com, which I mostly write in Markdown. It wouldn’t kill me to write HTML, but I don’t want to copy and paste a menu everywhere.

                          1. 8

                            Case in point about the downsides, the cv link is correct on the author’s homepage. It is not correct on this page. That’s an easy mistake to make, and I’ve definitely made versions of it. However, it’s much more pleasant to fix when you can fix it everywhere by updating a template.

                            1. 3

                              Thanks for the heads up :-)

                              Edit: Solved by sed -i 's,href="cv",href="../cv",' */*.html. In my mind, simpler than a CMS or static site generator.

                              1. 3

                                “Simpler”, sure, maybe. At least for now. But maybe it won’t always be such a trivial sed command. Maybe you wrote the html slightly different in certain spots.

                                A simple or custom-built static site generator would avoid mistakes like this altogether. You could have one file for your head element. Nicer menus, sidebar, etc. And you could still write most or all of it in pure html if you wanted to.

                                Simpler doesn’t necessarily mean better.

                                1. 1

                                  If you need the same template for all of your pages, then yes – a templating engine is a good idea.

                                  But if you don’t need this, then a templating system makes the process unnecessarily complicated. Creating a template in a special language and fitting all pages to the same mold takes much more effort than most realize, especially in comparison with just writing single HTML pages.

                                  For example, look at my software page. I have some fancy HTML and CSS to render sidenotes in the margin (unless you use a small screen). Because the page is “self-contained”, I don’t have to worry if I ever edit the style sheet for other posts. But if I used a templating engine, I would have to worry about it.

                            2. 5

                              Everything old is new again (or something like that)… you can always use server side includes for common elements.

                              1. 2

                                I like keeping my content and the final HTML site separate, and using the content to generate the site. It makes my content more flexible, but also makes generating the global menus easy, which is important to me so that my readers get a good experience.

                                1. 2

                                  I haven’t actually used it but the caddy web server appears to have built-in templating features: https://caddyserver.com/docs/template-actions

                                  1. 1

                                    Dreamweaver supported keeping sites’ themes consistent when I tried it long ago. It was templates or something. Maybe one of the open editors can do that, too. Otherwise, it would be a good feature for them to add.

                                    1. 1

                                      I hear you. I think the obvious solution then is to use something like PHP or SSI. Of course, that’s another layer of complexity, but not as much as a static site generator or CSS.

                                    2. 4

                                      Seamonkey compose is amazing. I’m glad to find someone else that uses it.

                                      Thunderbird’s email compose is a crappier standin, with a poorer UI no easy way to edit source.

                                      Tip for writing long formal assignments: numbred headings

                                      body {counter-reset: h2}
                                      h2 {counter-reset: h3}
                                      h3 {counter-reset: h4}
                                      h4 {counter-reset: h5}
                                      h5 {counter-reset: h6}
                                      
                                      h2:before {counter-increment: h2; content: counter(h2) ". "}
                                      h3:before {counter-increment: h3; content: counter(h2) "." counter(h3) ". "}
                                      h4:before {counter-increment: h4; content: counter(h2) "." counter(h3) "." counter(h4) ". "}
                                      h5:before {counter-increment: h5; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". "}
                                      h6:before {counter-increment: h6; content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". "}
                                      

                                      Some rough edges:

                                      • Sometimes you get swapped out of the source view (when saving? I don’t recall exactly)
                                      • Sometimes paragraphs are done with [p], other times with [br]. Occasionally something odd happens that changes the behaviour, I can’t recall, but it’s pretty rare.
                                      1. 3

                                        I love this. It’s sort of opposite to my own view where all of my writings are in plain text files, allowing me to do things that would otherwise be crushed by the layout. I think the “copy and alter”-method of authoring is genius in a world where everything is anxiously polished and uniform. To let the progression be a part of the published material is just beautiful. And exceedingly rare.

                                        1. 3

                                          If you fancy this, you might like sblg (disclaimer: it’s mine), which merges together HTML pages—template and content—with smarts to handle navigation, tags, and so on. You don’t even need to do the content in HTML: I do many of mine in markdown, bracketing the md->html output with the article tags sblg needs. I’ve used this for slide presentations, websites (e.g., Not Awful UW Photography, and so on. All managed by simple Makefiles.

                                          1. 2

                                            I like sblg, and I think it’s better than most static site generators (especially because it doesn’t use Jekyll’s awkward “front matter” system), but for my purposes, most of the same problems still apply.

                                          2. 3

                                            I write in straight-up HTML all the time, thank you very much :)

                                            1. 2

                                              :-)

                                            2. 2

                                              Writing HTML by hand is really not that bad if you take all the buld away:

                                              <!DOCTYPE html>
                                              <meta http-equiv="content-type" content="text/html; charset=UTF-8">
                                              <title>Writing HTML in HTML</title>
                                              <meta name="author" content="John Ankarström">
                                              <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
                                              <link rel="stylesheet" href="Writing%20HTML%20in%20HTML_files/style.css">
                                              
                                              <header>
                                              
                                                <h2><a href="http://john.ankarstrom.se/">John Ankarström</a></h2>
                                              
                                                <p>My name is <abbr title="first name [at] last name [dot]
                                                  se">John</abbr>. I study <abbr title="Russian, Swedish,
                                                  German, linguistics">language</abbr> at Uppsala University,
                                                  and in my free time, I dabble in <abbr title="Programming 
                                                  language design, web development, OpenBSD">technology</abbr>.</p>
                                              
                                                <hr>
                                              
                                                <a href="http://pohn.ankarstrom.se/cv">cv</a> ·
                                                <a href="http://john.ankarstrom.se/software">software</a> ·
                                                <a href="http://lamnafacebook.nu/">lämnafacebook.nu</a>
                                              
                                              </header>
                                              
                                              <h1>Writing HTML in HTML</h1>
                                              
                                              <time datetime="2019-06-19T00:00:00Z">Published on 2019-06-19</time>
                                              
                                              <p>I’ve just finished the final rewrite of my website. I’m
                                                not lying: this is the last time I’m ever going to do it.
                                                This website has gone through countless rewrites – from
                                                PHP to WordPress to Jekyll to multiple static site
                                                generators of my own – but this is the final one. I know
                                                so, because I’ve found the ultimate method for writing
                                                webpages: <b>pure HTML</b>.</p>
                                              
                                              <p>It sounds obvious, but when you think about how many
                                                static site generators are being released every day –
                                                <a href="https://www.staticgen.com/">the list</a> is
                                                practically endless – it's far from obvious. Drew DeVault
                                                recently <a href="https://drewdevault.com/make-a-blog">challenged</a>
                                                people to create their own blog, and he didn't even
                                                mention the fact that one could write it in pure HTML:</p>
                                              
                                              <blockquote>If you want a hosted platform, I recommend write.as.
                                                If you’re technical, you could build your own blog with
                                                Jekyll or Hugo. GitHub offers free hosting for Jekyll-based
                                                blogs.</blockquote>
                                              
                                              <p>Now, there's nothing wrong with Jekyll or Hugo; it's just
                                                interesting that HTML doesn't even get a mention. And of
                                                course, I'm not criticizing Drew; I think the work he's
                                                doing is great. But, just like me and you, he is a child
                                                of his time.</p>
                                              
                                              <p>That’s why I’m writing this blog post – to turn the tide
                                                just a little bit.</p>
                                              
                                              <hr>
                                              
                                              <h3>So what are the benefits of writing HTML in HTML?</h3>
                                              
                                              <p><em>There’s one less level of indirection.</em></p>
                                              
                                              <p>This point is simple, but hugely important.</p>
                                              
                                              <p>Using a static site generator means that you have to keep
                                                track of two sources: the actual Markdown source and the
                                                resulting HTML source. This may not sound too difficult,
                                                but always having to make sure that these two sources are
                                                in line with each other takes a mental toll. Now, when I
                                                write in HTML, I only have to keep track of <i>one</i>
                                                source.</p>
                                              
                                              <p>[...]</p>
                                              

                                              You can still format it to give the very same rendered page through trivial simple CSS.

                                              1. 2

                                                I’d rather use a static website generator that:

                                                • does not break backward compatibility every few months
                                                • does not require tents of dependencies
                                                • is packaged in Linux distributions
                                                • stays out of the way as much as possible e.g. by not forcing a fixed structure or language

                                                So far Pelican and staticsite fit the bill.

                                                1. 2

                                                  For my site (link on profile), I use PHP to dynamically create a blog from source files. In my case the source file is a single JSON file. I can write a Hugo/Jekyll compatible CMS in PHP that generates content dynamically.

                                                  1. 2

                                                    I thought I’d share some of my thoughts on HTML and static site generators. In this post, I explain and argue for what works best for me.

                                                    1. 2

                                                      Seamonkey is like the Windows XP of web browsers. Horribly out of date but still hanging on despite all common sense…

                                                      1. 5

                                                        I don’t agree. In terms of functionality and interface, it’s one of the best browsers out there, and it’s one of the only WYSIWYG HTML editors out there.

                                                        I think its continued existence is healthy for the web ecosystem; I’m afraid that sentiments like the one in your comment are increasingly leading to a monoculture controlled by Google.

                                                        1. 1

                                                          Preaching to the choir, buddy. I used Seamonkey back when it was just called “Mozilla” and “Netscape Navigator” before that. And then on and off once Firefox became a thing. It’s sad that they’ve basically just been playing catch-up to Firefox since.

                                                          1. 1

                                                            Well, I didn’t know you were part of the choir. It didn’t seem that way from your original comment.

                                                            It’s sad that they’ve basically just been playing catch-up to Firefox since.

                                                            Yes, Seamonkey is a great piece of software, and it’s sad that they don’t have enough resources or developers to properly maintain and develop it.

                                                      2. 2

                                                        Wow, you can do that??

                                                        1. 1

                                                          I’m currently refactoring the Makefile that generates my website and this gave me a lot to think about. I like your perspective here, questioning and ditching consistency between posts and letting them be unique. Puts the fun back into it. Thank you for writing this.

                                                          1. 1

                                                            I think a lot of the difficulties that people have with static sites is really a problem with the generators. The static site generator I use — ikiwiki — predates the current trend for static site generators (Hugo, et al). It has its quirks, and I’m concerned that it is fading into abandonware, so I would like to move elsewhere. But all the newer, popular ones seem to have enormous design flaws (complete lack of any kind of internal linking support; rigid ideas about source file layout…), so I’m stuck with IkiWiki for the time being. All the problems I have with IkiWiki however, are “internal” matters, and are not particularly reflected in the output, which I continue to be very happy with.

                                                            1. 2

                                                              But all the newer, popular ones seem to have enormous design flaws (complete lack of any kind of internal linking support; rigid ideas about source file layout…), so I’m stuck with IkiWiki for the time being.

                                                              A good summary of the state of the majority of static site generators, even the best and most popular ones. I hope you that ikiwiki continues to work for you, or that you find something else!

                                                              1. 2

                                                                Why does it matter if it’s “abandomware”? If it works, keep using it. What’s the obsession with continuously changing software?

                                                                1. 2

                                                                  It might not run after a while. If it’s written in standard portable C, it’s likely to keep working for a long time. But if it’s written in, for example, Python 2, lots of distributions are phasing out Python 2 in favor of Python 3.

                                                                  1. 2

                                                                    Bit rot. Bugs are not getting fixed. Patches are not being reviewed or applied. Long standing paper cuts continue to bleed. Unfortunately network software can’t generally stand still, because it needs to adapt to the changing circumstances it is deployed upon.

                                                                2. 1

                                                                  The absurd complexity that SSGs like Hugo and Jekyll introduce is the reason I created my own (LOL). It started off as a fun exercise in Python and I wanted something mnml. If you’re interested, here, have a look — vite. Disclaimer: it follows the “front-matter” method for parsing metadata.

                                                                  1. 1

                                                                    oh I had this idea of using git metadata to generate RSS feeds.