Hacker News Reader

Comment by lenwood | Hacker News Reader

I've been thinking of migrating my blog back to text only. When I was a student I kept a "blog" as a list of HTML files that I manually updated. I've been using Wordpress for the past ~15 years and am growing weary of having to keep up with plugin, theme or CMS updates. My blog is not worth this much effort to maintain, I just want a place to share essays and occasional photos. I need time to make the switch, but the simplicity of text only format is attractive.

View on HN

I wrote a <100 lines of python that takes a nested set of markdown files and outputs a mirror structure rendered as HTML (any file starting with a _ is skipped for works in progress), threw tufte.css on top of it and I have a page that loads in 9ms over wifi and renders so close to instant it's not worth measure.

Has syntax highlighting as well, beyond that I wrote it myself because it let me do exactly what I wanted the way I wanted.

Code is here if it's any use to you https://kopy.io/ibFMc

It supports Jinja templates and you can put meta data in the header so you can choose what template you want, override the title etc.

If you don't override the title 10-tricks-to-foo becomes "10 tricks to foo" automatically

I've used that script to write technical documentation as well, I just swapped out the template and everything else stayed the same, in terms of time to value reward it's up there for the most useful code I've written in a long time.

Out of curiosity, did you consider using pandoc? https://pandoc.org/MANUAL.html

For context/the uninitiaatd, I think of pandoc as the "postgres" of markdown-to-<blessed_format>: you can build your own text-format-converter, but oftentimes you can get 90% of the way there with pandoc, and fill in the rest with custom filters and elbow grease.

To whet your appetite, I have a personal site that checks your boxes, where the build script is basically one long invocation of pandoc and xargs. In my experience and that of others', building on top of pandoc can get you to quite satisfying places and workflows (e.g. https://www.gwern.net/About).

(Also, fwiw, we use it at my place of work for writing versioned technical documentation, as well.)

Keep on plain-texting! :)

I've used it in the past but I reach for Python most of the time.

Are you me? That is almost exactly what I did, even including the part about tufte.css and syntax highlighting.

I ended up exporting all of my old blog posts from WordPress. Rebuilding the entire site (~370 pages) takes about 4 seconds.

The biggest problem I found was that I had to modify tufte.css to make it work well on mobile.

Care to post your site?

Mine, if you are curious: https://sheep.horse/

Great minds, my site is on my real name and I'd rather not connect my user name with my handle so publicly, it's got nowhere near the amount of content yours has though.

In my case there is a certain irony in writing it in Python the lazy way since I'm a full stack dev who writes typescript, js and PHP for work.

Never trust a builder with a finished house I guess applies, I didn't want anything I'd have to maintain.

I really like the margin notes layout of your site! Might have to steal that.

edit: oh wait that's what the Tufte css is! What tweaks did you end up making?

Not to be annoying and plug my own projects, but I've tweaked Tufte CSS to work within a jekyll theme: https://et-jekyll.netlify.app/

It might have changed recently, but tufte.css used to behave badly in portrait (say on a mobile phone, or just with a narrow browser window.) Part of the problem is just the design works a lot better in landscape.

It took me a lot of fiddling before I managed to find an acceptable compromise.

If I was going to start again I might consider implementing the margin notes differently. They interact oddly with each other and image captions.

I recently stopped using a static site generator for my personal site [1] in favor of just manually maintaining a bunch of HTML files, for similar reasons. The last straw for me was a nonpassive change to the site generator mysteriously breaking the homepage. Themes are frustrating as well since they either constrain you or force you to spend time figuring out how to shoehorn what you want into the theme. I only post occasionally, and keeping all the pages consistent with each other isn't as important to me as being able to post a page that looks however I want it to with minimal hassle.

[1] https://brokensandals.net/

I'm using what is probably the simplest static site generator: cat.

  for f in texts/*.html; do
    cat preamble.html "$f" postamble.html > out/$(basename "$f")
  done

The front-page is written manually.

I did something along those lines once, but I used https://github.com/susam/mdme as the preamble so I could write the posts in markdown rather than html. The index was an extra line to add links to index.html.

I do something like this. You can write HTML almost as simply as text if you ignore some current best-practice.

Google's guidelines for HTML5 [0] are surprisingly good and concise. You can omit most closing tags, and even many "structural" tags are implicitly opened. This is a 100% correct and complete HTML5 document:

    <!doctype html>
    <title>Title of the document</title>
    <p>A paragraph
    <ul>
        <li>First item
        <li>Second item
    </ul>
    <p>Another paragraph

writing html tables by hand is especially pleasurable due to the auto-closing tags. As I see it, modern HTML is so concise that markdown is more of a burden than an aid. In most cases, we would be better off writing html directly than markdown. Maybe the only thing that I miss is that an empty line creates a paragraph tag.

[0] https://google.github.io/styleguide/htmlcssguide.html

You've touched on a slightly interesting topic. HTML has never had strict parsing requirements, for example, it was completely permissible in HTML4 to leave a tag unclosed if you subsequently opened a tag which could not be nested (as in your example of two <li>s in a row). Containers have always been implicit in most cases, so it's perfectly acceptable to start a table row without having started a table, the parser will start the table when it encounters the row. This is ultimately because HTML is derived from SGML, a markup standard that is visually similar to XML but with very relaxed parsing.

However, HTML4.1 for a time faded in popularity compared to XHTML, which was an "HTML-like" markup derived from XML rather than SGML. XML has significantly stricter parsing rules, for example always requiring full closing tags, trailing slashes on self-closing tags, etc.

XHTML's popularity seems to have been in large part a result of the IE6 backlash. Problems with web standards were widely perceived as a high priority for the web. This was the time period in which people kept putting "W3C Compliant HTML" badges in their footers. Because XHTML had stricter parsing rules, it fit into the general scheme of emphasizing web markup that was "correct" by allowing for strict automatic validation. Because it was XML-compliant it also fit nicely into both the popular-at-the-time "Semantic Web" (e.g. XHTML documents could be validated against XML DTDs/schemas) and dovetailed with browser support for XSLT (in which case a document could be sent to the browser as semantic XML with an XSLT "style sheet" for transformation to XHTML for presentation), which was one of those things that seemed like "the future" for about five minutes. I had done my personal website that way for a hot minute.

XHTML's vogue was somewhat short-lived, while it was a big part of the "web" scene in e.g. 2007, it was largely forgotten the moment HTML5 because available. What seems to have survived from XHTML, though, is a much stricter approach to writing SGML being seen as more or less required. I think a lot of people "grew up" on XHTML, quite possibly unknowingly, and so errantly view HTML itself as XLM with the subsequent parsing rules.

As always, there is often value in being explicit and verbose in markup in terms of maintainability. But in a lot of cases readability and maintainability are not harmed or even improved by saving some typing... as in cases like lists and tables.

That said, a big part of the phenomena is that hand-writing or reading HTML is decidedly out of vogue today, and so in general the readability quality of most HTML on the web is extremely poor, generally a result of it being generated by templating or composable component systems which often abandon basic indentation, as well as by the popularity of frameworks with unusual use of HTML such as non-semantic class-driven CSS frameworks. Of course this phenomena isn't entirely new, FrontPage and DreamWeaver were popular in their day and generated some pretty terrible markup, but it seems to have become more common, rather than less, for HTML to be machine-generated and thus extremely unpleasing to humans.

That's very cool. Do you have a good solution for inline math?

I wonder how far could one go with just Unicode symbols. Entry would probably need a proper editor support. Additional use of sub/sup could also help.

https://en.wikipedia.org/wiki/Mathematical_operators_and_sym...

Org mode supports inline Latex that can be exported to html.

Here's a nice demo on how to write tech docs using Emacs and Org mode https://youtu.be/0g9BcZvQbXU

The only reasonable thing I have found is mathjax.

Otherwise, if you math is just inline latin/greek symbols without 2D formulas (integrals, summations, etc), you can get away with unicode symbols and sub-indices.

Maybe KaTeX https://katex.org/

I think one of the advantages is that markdown is not just that it is concise, but that it is also somewhat limiting.

If someone worked on a large team and moved all documentation from markdown to HTML, I think they'd quickly grow to become something a lot more messy than your example.

Markdown was made to support inline HTML and most parsers/compilers will support it by default (including Github).

Already has best of both worlds.

Yes, but when you ask someone to write markdown they usually write markdown. And when you ask someone to write HTML, they typically add closing tags.

I wrote up a few of my own thoughts[0] on moving away from writing markdown to writing HTML directly. At this point I have a small bit of code to wrap things into an <article> tag include a <header>, <footer> with links to a home page and include some boilerplate like <meta> tags. I don't think I've sacrificed anything in terms of best practices and actually gained a few things in writing more semantic HTML which I think aid in assistive technologies[1]. I actually hope people will "view page source" on my pages anymore -- a big part of getting to where I am has been testing against alternative browsers like eww and w3m.

[0]: https://idle.nprescott.com/2020/why-bother-with-markdown.htm...

[1]: https://sourcehut.org/blog/2020-05-27-accessibility-through-...

I've been writing HTML directly for my blog [1] for 20 years [2] and back around 2003 I started to be a bit more pedantic about the HTML I use, so I always (try to) close every tag. About five years ago I set up a gopher server [4] and use it to mirror my blog. I went the easy route and decided to use Lynx to convert the entries from HTML back to text, and ... it looks horrible. Now that the Gemini protocol [5] has stabilize, I've decided I should convert the HTML to text myself, and because I decided back in 2003 to close every tag, it's easy to do (after spending an evening cleaning up a few entries here and there---there are over 1,000 entries pre-2003 that need extensive cleanup though---sigh).

The optional tags make it easier to write, but make it far harder to mechanically process later if need be.

[1] http://boston.conman.org/

[2] It's been only the past year or so that I've created my own markup language [3] to render the HTML, and it's the resulting HTML that I store.

[3] A mostly-up-to-date sample of what it looks like: https://github.com/spc476/mod_blog/blob/master/NOTES/testmsg And the Lua script that parses it: https://github.com/spc476/mod_blog/blob/master/Lua/format.lu... It's still buggy, and there are corner cases I know how to avoid, and I'm not recommending it to anyone else, as it works for me.

[4] gopher://gopher.conman.org/

Nice. I went one step further because I don't even want to write HTML. I built my website in PHP to parse plain-text files then sort and display them by creation/modification date or title/category. The only markup in the text files is usually <b>, <i>, and sometimes <a href>. This way I can write in whatever editor I feel like, export as .txt, then scp the file right to my site for publishing. I guess it's like a custom CMS? Either way, it really helps my ability to write for some reason.

If you want text only (especially if it is only ASCII text) and not HTML, consider using Gopher. You can serve them with both HTTP and Gopher, actually. (If you want to accept public comments too, then NNTP is another possibility.)

If you do want HTML (or possibly Markdown), then of course HTML will do. Just use plain HTML (perhaps with a common header and/or footer, added either ahead of time or using server side includes); no CSS, JavaScripts, decorations, etc.

I created https://neat.joeldare.com as a micro css "framework". Check it out.

I've also been experimenting with just using md files on GitHub, which is very easy to write and publish. https://github.com/codazoda/markdown-test

You can do something "similar" with archive.org (With automatic directory listings)

Suppose you want a really long lived store for your plain text or html files (archive.org is unlikely to go away anytime soon)

1) create an account on archive.org

2) upload your folders of files as an Archive.org item

(works best if you upload with a root folder included so that the archive.org meta files get created outside of your first level documents folder)

Your index listing will live under a url like:

https://archive.org/download/test_blog_2020/test/

(or even sub-folders like: https://archive.org/download/test_blog_2020/test/blog/)

(note that "test_blog_2020" here is a global unique identifier you can customize when you first upload to archive.org. as long as it is available of course)

Each file will have its own url like: https://ia601506.us.archive.org/4/items/test_blog_2020/test/...

(which means you can use relative links in your html and they will just work)

And you can use the "Edit" functionality to add more files to your folders:

via a url like this: https://archive.org/edit.php?edit-files=1&identifier=test_bl...

wow, I love your solution using github even if you want to migrate of github down the line its still all Jekyll +plugins underneath

Do you know if there is a way to have an automatic directory index page? (i looked around the gitubpages/Jekyll docs but couldn't find a way at first glance)

i.e. What I mean is I would like to throw a bunch of md files into a folder and have a url that outputs the hyperlinked dir listing

One way would be to use the Github API to retrieve all the filenames:

https://stackoverflow.com/questions/25022016/get-all-file-na...

Then use Javascript to create the index page.

thanks for the suggestion, but I was looking for a "zero code" solution like parent. i.e. it would use some Jekyll feature that is running behind the scenes

meanwhile after some googling this may be it (not tested though)

https://cl.mt/blog/github-pages-indexing-directory

Reply on news.ycombinator.com