Writing HTML in HTML (2019) | Hacker News Reader

Writing HTML in HTML (2019)

john.ankarstrom.se

103 pointsTomte77 comments

>Doesn't this mean that I have to type a bunch of boilerplate every time I create a new blog post? > >My simple answer is: just copy it. My more advanced answer is this: > >1. Make blog posts and pages self-contained – in other words, have each post or page reside in its own folder, with its own scripts and stylesheets. > >2. When you want to write another post or page, copy the folder of an already existing post or page and edit it. > >3. If you find the previous step too much work, write a shell script that copies the directory and removes the old content for you.

Shell script eh ... OK - that'll work ...

And now you want to adjust your style and have it apply it to all your existing page. Another shell script? That'll work, though you're on your way in recreating a static site generator.

He actually addresses this by saying he doesn't care about the previous posts. They'll just have a different format and are a time capsule.

Did you see his update below that paragraph? He admits that he had to update everything, and his pages are not currently a time capsule. It basically negates his entire message.

FWIW, the screenshot of the page doesn't actually look like how the page looks like currently. One could handwave and say that's intentional, but IMHO it looks as though the styles are broken (in particular the text in really small font and the yellow highlighted text)

I think the moral of the story here is that if you're going to be advocating for HTML over a SSG, then perhaps it would make sense to invest a bit of time on a styleguide page, or take a bit more effort to leverage default styles (in the style of http://motherfuckingwebsite.com/), or just commit to inline styles to lock down the individualistic look of each page (if that's what they want). Being wishy-washy about style management over time is not going to age well.

> Shell script eh ... OK - that'll work ...

There's Blogit shell script https://pedantic.software/git/blogit as well as many others, no reason to write your own.

There's also jekyll and countless other tools too =)

I’m having trouble telling if this is satire, but I think it’s not.

The arguments are fairly weak, notably:

1. Using a static site generator, you have to keep track of the source code and the build (which the author suggests is more “source code”)

Nope. I could look at the dozen or so static sites sitting on my hard drive — I’ve kept none of the build directories. I simply git push the source and Netlify takes care of managing everything else.

2. > Let's say you want your site to have a specific directory structure, where pages are sorted under various categories. With Jekyll, this is practically impossible

Again, I don’t agree that this is even an issue, but there’s also nothing stopping you from using whatever directory structure you want. I don’t use Jekyll much, but that’s the thing about SSG: you can use the one that’s as simple or as complicated as you’d like!

You could even generate your site with a simple bash script:

for p in in/*.html; do cat common/header.html in/$p common/footer.html > out/$p; done

As you can see there’s very little stopping you from preserving whatever structure you want.

In fact, the author even suggests this! >If you find the previous step too much work, write a shell script that copies the directory and removes the old content for you.

Okay, so if you already have a script that copies content, you basically have a very bad manual SSG that doesn’t keep everything in sync.

I don’t really think any of this is easier than just spending the afternoon figuring out a basic SSG.

> and XYZ takes care of managing everything else.

that's external dependencies. I guess that's a nogo for the author.

You spend the afternoon doing this, then a few more to make it "generic" then it's dozens of your successors swearing at you for doing something so complex to solve a problem so simple.

I don't think it's satire.

You're suggesting an SSG, Git, Netlify, and shell scripts. Is this really easier than HTML files on a server? I can do everything with HTML files, and if I need templating I can just use PHP.

I mean, where are you keeping your backup files for if the server fails?

On your local computer?

Or Dropbox, Google Drive, GitHub, a floppy disk.

Yes it is!

Netlify is easier than HTML files on a server. Basically no effort to host a static site, even one that is generated.

An SSG such as Jekyll, Hugo, Gridsome is potentially easier than HTML files because it uses abstractions to avoid repetitive, error prone HTML such as your lists of posts, previous next, sitemap, etc etc etc. And writing articles in Markdown is so much nicer than HTML.

Git is easier than not using Git, whether or not you use an SSG.

Shell scripts were offered as a poor mans SSG, so lets ignore them.

SSG can be annoying when the templating sucks. I found Hugo annoying in this regard, Jekyll is fine, Gridsome is great, at least on par with PHP when you step outside the box. I think an SSG oriented framework is going to reduce how much templating/scripting you have to write massively.

Hosting on your own server, setting up IPs, SSL, Nginx, some kind of deploy script (sftp or whatever) are not particularly hard but with Netlify it's all handled so easily.

Theres no contest here

Nobody suggested hosting on your own server. There's 74824884 providers, free and paid, that let you drag and drop html files from the left to the right.

Well, there is a contest because I'm not convinced.

Your solution requires researching a bunch of SSGs, deploying and configuring them, and setting up a version control system (which you don't need for a low-stakes personal blog).

My solution is a text file on a web server, using HTML (which I already know) instead of a pseudo-format with a gazillion implementations.

If I'm wanting to write about something I want to write about that thing, not write about that thing in the midst of a bunch of extraneous fluff like header tags, script tags, CSS, etc.

The author's thoughts about layers of indirection are confusing to me, I'd actually take the comparison the other way. If I'm not using markdown plus a static site generator now I have to keep track of things like layout, styling, script tags, etc myself plus the actual writing I was intending on doing.

I used to have an extremely simple markdown server. It presented 2 types of page, an index and an article. The index simply read the /content directory on the server. Requesting any file under /content would render the markdown into the article page and affix a date and time from the .md file's metadata.

Takes <1 hour setup and means you never have to copy and paste random files or do whole site page transformations (as the author has admitted to in that very post) to clean your mishmash HTML beast.

The author suggests using a visual html editor and copying any code you need for layout, navigation, etc. You can't deny that's infinitely easier than rolling your own SSG and using markdown.

Ah, well in that case the note about layers of abstraction don't really apply very well. A full WYSIW(YG/YM) editor is not going to generate HTML you actually want to read or write.

Otherwise we'd all be making sites in Microsoft Word given its ubiquity! :D

The HTML that is generated by Seamonkey Composer is reasonably editable as plain source. (Actually it is much more pleasant than using exclusively Notepad, because the auto-indentation is reasonable.)

However, Microsoft Word generates extremely bad HTML. Don't use it.

Like the div soup react (or any other js framework) generates is any better. In any case, I don't understand the need for clean HTML if I don't have to read or write it. Which is supposedly true if I'm going to be using a wysiwyg editor or you know a web browser to read the actual content of the damn page and not its markup.

> I used to have

what happened to it?

This was several years ago now, during my pre-university days. I lost access to my hosting and my domain due to lack of funds, dead hard drives (didn't use any versioning) etc.

At this point I don't write about much, so I haven't revived it.

I love this because it's a reminder that simplicity is just around the corner if we only are open-minded to rediscover old truths. No complex server software, no package managers, no git, no SSG bullshit - just basic HTML and CSS.

I am not a developer. I am simply someone who is fascinated by creating software and websites. I remember taking a HTML/CSS class in high school 12+ years ago and it was one of the most fun classes i've ever taken. Didn't really know i could make a career out of it at the time, but i wish i did. With that said, i love visiting websites that are pure HTML/CSS. They are fast to load and easy to read.

Well, most developers hate simplicity and simply love automation. From some point on automation usually becomes a process that's merely shifting complexity from a manual process to maintaining a growing software stack.

I'd say for a simple web blog managing its entries by means of html files on the server is a valid solution. I am not sure how the author maintains an index of his blog entries this way, but updating an HTML index page manually does not seem like a huge effort to me.

We always forget we move away from simplicity - this won't scale and if you want to make a global structural change you're now performing the operation as many times as you have pages.

I find myself coming back to a metaphor that was in the comments here yesterday - yes, this is a beautiful, stylistic self portrait, but if your job is to paint the whole house this is a terrible way to do it.

In the context of this post, i.e. publishing a small personal blog, simplicity works well.

Is it simple though? Copy & paste into a WYSIWYG editor is pretty error prone, and he's already talking about creating several shell scripts to keep things in sync. Seems a bit like re-inventing the wheel, no?

Unfortunately basic HTML has one glaring problem: it has no concept of code reuse. No layout, no shared footers, nothing like that. Frames were probably HTMLs answer to reusing common elements, but oops, frames are a disaster. Instead it was so bad there were actually Apache extensions to reuse HTML (see server side includes).

Then compound this problem with something like a blog where you have hundreds of pages who all need to have their menus updated every time you post something, and yeah...pure HTML is just unacceptable.

IMO the solution is to design around these constraints, ie, don’t include a menu on your blog posts, just a link to the home page, which has a list of all the posts.

And then you've completely destroyed the point of hypermedia.

What do you mean? You can still like to other documents, just drop the idea of linking to the same list of documents on every page

That works, but it's not what users want. Granted this is personal anecdata, but I've spent years pushing back on client expectations in the name of architecting things in a way the web supports at the lowest levels, and it's been an exercise in failure. No user is going to accept that behavior in a blog, and frankly as a reader on the internet, I find that solution pretty lame as well. I absolutely agree with minimizing the impedance mismatch between how we develop and how the web actually works and the associated tool-chain simplifications that come with that, but at some point we have to accept that web tech just wasn't designed to do what we need from it and add some layers on top. The challenge is balance.

I am not sure what is so radical about this. Let's take Medium as an example (pulled some random article from the front page):

https://medium.com/change-your-mind/the-simple-40-minute-mor...

What we have is, essentially, a blog post that could be written in pure HTML, and a link to the user's profile, which looks like this: https://ashley-richmond.medium.com/ This is one of the most popular blogging platforms and follows exactly the hub-and-spoke navigation model that I described.

Now, I do what to clarify, what I proposed is how I would build a website using plain HTML. I would certainly not go so far as to claim that it is the best way to build any website, SSG's have many advantages, but what I'm saying is that if one is going to write a plain HTML website, the easiest way is to accept the fundamental limitations of that approach, including a hub-and-spoke navigation vs a navbar. If you're writing a plain HTML site, you're probably a bit iconoclastic and willing to accept breaking some standard practices.

By that point though, you're dropping actual useful website features. What if I want a consistent style across my pages? What if I like restyling the whole website & I don't want to manually edit dozens of HTML files to do that? What if I think a header bar or a "recent posts" section would be nice?

I'm not saying it's bad to design a website in plain HTML, but it is critically limiting, and I wouldn't recommend it over a simple generator setup. If you're really opposed to using a fully-featured SSG, it'd be pretty simple to write a shell script that uses mustache(5) [1] to plug html articles into a template. That's almost as simple and clean as plain html, but it's a real step up when it comes to what it lets you do.

[1]: https://mustache.github.io/mustache.5.html

I want to clarify -- what I'm describing is how I would design a simple website using plain HTML. I have no opposition to SSG's, but just want to present an option for what it would look like if you eschew them completely.

The HTML vocabulary doesn't have and doesn't need these because SGML, on which HTML is based, has entities and many other constructs for templating. In fact, both SSI in default config and embedded PHP use a (simplistic) form of SGML extension syntax (markup comments and processing instructions, resp.) for equipping static HTML with dynamic features, though SGML has much more powerful ones.

So are you suggesting the solution is we should write SGML and then have that converted to HTML to fill the role of a static site generator?

I was merely commenting on why HTML itself doesn't have the features you mentioned. But yeah, authoring HTML in SGML is the most natural thing given HTML's origins. It doesn't have to run as a static site generator since SGML can run right in the browser and in the web server backend (see eg my project here [1]). Though using SGML as static site generator from the command line or Makefiles is also extremely useful, and maybe the most appealing for developers or when static site hosting is desired ([2]).

[1]: http://sgmljs.net

[2]: http://sgmljs.net/docs/producing-html-tutorial/producing-htm...

This is a whole avenue of exploration I had never even considered, thank you very much for responding with this.

Correct - though as designed that's a tooling problem, not a spec problem. Consider the pre-web world: You don't have reusable components in your printer, you manage stylesheets and templates in your word processor.

The original assumption from TBL was there would be much richer tooling to allow everyone to compose HTML without knowing tags, but for various reasons that's not the direction Andreesen et al took Netscape. And third-party tooling (like SiteMill) end up focusing on developers and evolved into things like DreamWeaver.

Hence the mess we're in today: the world's greatest publishing platform, and it's near-impossible for non-technical users to start publishing directly to it as conceived. Good news for Wordpress and CMS vendors, but a road sadly not taken in so many other aspects

People see all of the simplicity through rose tinted spectacles.

Copy and pasting bits of HTML around was a chore and was prone to error.

No decent source control (the source control at the time was garbage and tbh was a relatively new concept in web dev) meant that you had no idea what you had done previously or why. I remember have lots of zip files with dates and README.txt in there.

No package managers meant that I had to keep track manually of scripts and CSS in folders.

Nah I don't think I will be going back to that madness thanks.

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

People have no idea how this simple thing cost so much money in so many companies. The time we spend shoe-horning stuff into stubborn frameworks someone senior, architect, or powerful in general like without having used it is sometimes more than half the budget clients pay for a solution.

And it's not just HTML. It's using Mule for API connection (70% of our time spent fixing Mule, swearing at it or hacking it), using Grails for Java servers (this was horrible and already happened to me twice, I could convince the CEO and bypass the leads to rewrite it in a language we all understood the first time, but the second time the company had to close due to endless productivity sinkholes and 200 employees turn around in 1 year...BECAUSE no one understood what the hell was being done), it's using custom made code generators to consume field lists in very complex models which everyone forgot the workings of 10 years later and new guys spend most of their time for months just hacking the generator to add very low value changes, and the list goes on.

Adding level of indirections to solve simple problems in an evolving system is now something I try to avoid. I even have to fight "geniuses" by telling them that we need to do the dumbest possible solution first and see what we need, rather than one more crazy framework solving a problem we may never have. And I don't always win...

I agree a lot with the post, but using a WYSIWYG editor isn't really writing HTML is it? You can write HTML in your text editor, get piecemeal automation as you go such as sharing a common site menu or other boilerplate via text variable substitution, generate a table-of-content as page nav menu, validate your HTML, use markdown, support user comments, all the way up to using templated lists and forms for databases if you wanted to using pure SGML.

That's a good point. So it's not really static site generators vs HTML, it's code based static site generators vs WYSIWYG based static site generators.

Or just write your own static site generator. For extra fun, before you begin, browse random blogs and take a drink whenever the first post is about how they built the static site generator for their blog.

I agree. Writing a static site generator can be very easy to do. I just use pandoc, a makefile, and a tiny python script to insert articles into the index. Stay tuned for my blog post.

This is exactly what I do for my website - I write articles directly in HTML code, not Markdown or something else that gets translated to HTML.

I draft my articles in plain text or in a WYSIWYG editor, without markup. After I'm satisfied with the content, I go and manually wrap the text in the appropriate markup tags. This includes both inline tags such as <strong>, <code>, <var>, <abbr>, as well as block tags such as <h2>, <p>, <ul>, <li>, <table>, etc.

The major reason I use HTML is because I want to use the full palette of HTML features. I don't want to figure out how to use <dl>/<dt>/<dd>/<thead>/<th> and nested lists in Markdown for example. And if I needed to use attributes like <span lang="ja" class="animate">, then any syntax other than HTML offers no simplification anyhow.

I used to write my site the same way, but I eventually got tired with inserting tags (and closing tags) in my text. Why type more than I need to (and possibly forgetting things) when Markdown can do it for me, and passes any embedded or customized HTML tags, too?

I don't speak for everyone as situations differ. In my case, I'm not just writing long-form English prose, but I write technical articles that need stuff like <var>/<sup>/<sub>/<code>/<abbr>, decent control over block structure, custom-styled content, and lightly interactive content. You'd have browse my website to see examples of my existing work and why raw HTML works much better for me than Markdown/AsciiDoc/troff/etc.

I did a prototype of my personal news site in HTML/CSS (no JS for maximum compatibility) with every intention of eventually automating the generation and making a dynamic submission system. I still haven’t bothered because it’s always been less time consuming to just to edit it by hand, and it affords me the occasional customized post/entry whenever I need to post something special.

Literally only using either Notepad++/FileZilla on desktop or an iOS FTP text editor combined with iOS Shortcuts if on mobile to generate and apply new posts.

For Notepad++ I saved macros for different post formats, the macro pulls the URL from my clipboard and wraps it in the HTML according to which shortcut key.

The iOS workflow does the same thing and lives as a cluster of app icons that trigger custom iOS Shortcuts in a folder on my Home screen, I just tap it, it pops-up an iOS input modal asking for the post title, then automatically wraps the HTML around both the text I input as well as the URL I already copied onto my clipboard, then takes the entire HTML chunk and overwrites my clipboard with it so I can paste into the index.html via the iOS FTP text editor.

In both cases it’s simple and fast, on iOS the FTP editor is always editing the live file, on desktop I just download the latest using FileZilla prior to doing any edit/upload. When on desktop I also (when not in a hurry) commit the latest version to a git repo.

(For larger and less commonly used updates, like formatted sections or special link highlights, I just have a templates.html file that I copy from as needed.)

I love what you are basically suggesting is the jerry-rigged version of Frontpage or Dreamweaver.

I mean don’t think of it as a suggestion so much as a natural outcome of the prototype becoming the “official” version due to it being less expensive to finish and more importantly less expensive to change. I still intend on automating it someday, and always told myself I would once I confirmed exactly what I wanted to automate and how.

So far, the ability to change the formatting and add custom edits without having to do any real development or deploying anything has been higher value and lower barrier of entry so I’ve yet to find the need and I can update the site in seconds.

The only real motivation to automate is for some things like the publishing date and Bitcoin/gold/silver prices at the time, but so far I still have just been editing it manually, and sometimes neglecting to update entirely if I’m in a hurry to just add a breaking headline.

I hadn’t thought of the take away but to me that’s what it should be if I were to highlight one, let the productive outcome vs. cost dictate the level of effort, which for web may naturally fall into somewhere on a spectrum between static HTML and cloud container deployments with automated testing and builds from CI deploying a dynamic data driven platform, depending on your needs.

Einstein said: "Everything should be made as simple as possible, but no simpler". This is an instance of "but no simpler".

Any non-trivial page written in only html will eventually evolve into a self-written static site generator, the author even suggests that by recommending shell script to automate html generation.

The real simple solution is to use a static site generator, however one could debate whether it is better to write it yourself or to use an existing one.

> HTML is unpleasant to write.

Is it really, though? HTML is a very deep toolbox, but to write blog articles you really only need a handful of tools on the surface level. If you were previously using markdown, all you need to do is review the basic syntax[0] to figure out the equivalent HTML tags. Writing HTML is hardly any less pleasant, albeit a little more verbose, if you just stick to those tags.

I think primary value of languages like markdown is input sanitation. If a user makes a mistake in their markdown syntax, there's no risk of it breaking other elements on the page. But when you as the host are the only user, I say pure HTML is the way to go.

[0] https://www.markdownguide.org/basic-syntax/

To add to that - if you prefer writing the body of the post itself in markdown, and write in VIM, here's a little snippet that might help:

:%!markdown_py

where markdown_py is your markdown-to-html tool of choice. This will take the whole buffer and turn it into HTML; Otherwise, just select what you want transformed in visual mode, press : and go use it like this:

:'<,'>!markdown_py

Just felt the need to share - any command line utility can be used in VIM :)

(Emacs, VSCode and other editor-using people feel free to chime in, I'm sure there's lots of cool approaches to this)

If you want to write pages by hand you might look into Cured HTML:

https://technology.reclamation.institute/pages/cured-html

It's a way of styling markup so that you don't have to manually enter P/BR tags.

Add ~30 lines of PHP to handle standard boilerplate (html, head, body, etc) and you can manage your website by uploading nearly pure text files to a remote folder. Or by authoring them via command line editor through SSH.

If you don't want any languages at all except HTML/JS/CSS, you might even use Server Side Includes.

I've tried quite a bit of solutions to manage my website for decades. The solution closest to the OP was a plain HTML plus postprocessor (PHP, but only at the preamble to set up the output buffer). I managed to put some hundreds of posts in that system but eventually gave up because it was a pain to read, not write. I desperately needed to read the work in progress to manage my narrative and I couldn't do that with HTML. An HTML editor was not an option because, in addition to being PHP, custom elements to be postprocessed couldn't be easily visualized in conventional HTML editors.

I had since went through (more than one) wiki, a custom Python server, m4 and make scripts and several SSGs. (My latest website uses Hugo.) Nowadays however I don't really care; as long as I can read that damn thing I can write anything I want. Do not pursue the perfect website solution; pick a working one, stick to it and don't look back. If it means a plain HTML, so be it.

Previous discussion: https://news.ycombinator.com/item?id=20238289

And if you want to do this again, see the followup post they made more recently 6 months ago:

http://john.ankarstrom.se/html2/

It's fun to see articles like that being posted on HN; it's reassuring, in a way: I've been building my own SSG ( https://github.com/hexanal/fredmercy-blog ) to be "simple but powerful", and by my own admission it's already a bloated mess, understandable only by its insane creator. At some point, just like John here, I once wondered if I should go back to straight HTML.

If we're talking about "Developer Experience", it's cool: I can edit everything with ease in my IDE of choice. To be honest, what I'm missing most with these solutions is a Content Management part: the ability to add content to the website from a mobile device, for example, would be killer.

Now all I need is an awesome WYSIWYG HTML editor for mobile...

I'm a big fan of minimalism and I made a tiny html/css framework for doing this.

https://neat.joeldare.com

I still use Markdown for most of my blog posts. I just let GitHub build it for me. But I'm a fan of always thinking about the simple solution.

My theory is that static site generators took off because of young developers learning via local development without the aid of a web server.

Old-fashioned HTML/CSS with minimal server-side scripting can do all of this stuff easier with fewer limitations. And you can have dynamic content.

The strength of SSGs is that you have the power and simplicity of plain HTML & CSS, but with two special features:

- the ability to quickly change styling details on all of your pages

- a markdown engine, so that you can write posts more quickly and ergonomically

There are other nice features SSGs bring to the table (automatic RSS feed generation for instance) but those two features are the main things that stop me from writing directly in HTML. Especially the first one.

I currently think about a tool that does a liiiiiitle bit of what a static site generator does – but based on already valid html input. https://mensuel.framapad.org/p/r.0c8792b90b31b50a91455713a36...

And just help a little bit with consistency in terms of keywords & navigation so as there can be a bit of structure in the chaos.

Maybe one could even go so far to add a xslt (html -> html) and amend that navigation etc. late in the browser.

If you really want something simpler than using a SSG, you can always use pandoc to convert markdown files to HTML. With a one-line command, you can take any arbitrary .md file and spit out .html.

As tinkerers, the personal website is seductive. And that’s fine if you’re mindful of it, or you’re just starting out. But at a certain point it’s a good idea to be clear on what problem you’re trying to solve. And be wary of solving a problem that doesn’t exist, and may never exist.

There’s an opportunity cost to spending a bunch of up-front time setting up a bunch of crap you may never take full advantage of. You could be focusing on the content, finding an audience.

It’s helpful to zoom out and remember the timeless mantra: “You ain’t gonna need it.”

For me this appears to be the wrong combination of a solution and a problem.

The problem is tech churn, versions are obsolete faster than you can download the packages and the whole ecosystem moves way to fast.

The solution is to choose simple and stable solutions. Build a shell script, use low-churn technologies, etc.

I had a site like this before. I simplified it further by not having a navbar on each page. Every page would share a css stylesheet and have a single link to the homepage. The homepage would have links to all the pages. No templates needed.

Shameless plug:

https://fctorial.github.io/posts/constexpr.js.html

A static site generator that uses javascript. You use the browser runtime to generate html.

Lol, this is the top comment for me right now.

Blog post: don't use static site generators. Top comment: take a look at my static site generator!

That must be because this comment is new (0 minutes ago). Hacker news pushes new comments near the top.