5 ms·

> In Octopress, blog posts start with a section like … I removed these sections replaced them with maps in a file called posts.edn: Part of blogging in markdow

> In Octopress, blog posts start with a section like … I removed these sections replaced them with maps in a file called posts.edn: Part of blogging in markdown files is universal portability: you can use any editor, parser, doc publisher, or site generator on a set of generic plaintext files. Those headers were “YAML Front Matter” standard metadata, and for portability belong in the file not elsewhere. This is used across pandoc, static site gens, Markdown parsers, and Markdown editors (VSCode, Sublime, Bear, Ulysses, Obsidian, Typora, etc.). https://jekyllrb.com/docs/front-matter/ https://jekyllrb.com/docs/front-matter/ https://forestry.io/docs/editing/front-matter/ https://forestry.io/docs/editing/front-matter/ https://assemble.io/docs/YAML-front-matter.html https://assemble.io/docs/YAML-front-matter.html https://blog.valeconsulting.co.uk/2019/09/05/automating-documentation-with-github-markdown-part-1-setting-up/ https://blog.valeconsulting.co.uk/2019/09/05/automating-docu... https://docs.zettlr.com/en/core/yaml-frontmatter/ https://docs.zettlr.com/en/core/yaml-frontmatter/ And finally, Clojure library designed to parse front matter: https://github.com/liquidz/frontmatter https://github.com/liquidz/frontmatter

capableweb 5y ago
The bog-standard Markdown editor would output the front matter directly in the post, unless it specifically has support for front matter. So if you're really aiming for "universal portability", get rid of the front matter. And there is nothing wrong with inversing the control of the metadata. Instead of having each file carrying the metadata and you need to iterate filenames to get the full list, it's OK to have a index that has the filenames to read + the metadata. Simply a matter of preference and not really a requirement for someone to say that they "blog in markdown files", whatever that means.
- onion2k 5y ago
  Simply a matter of preference... It's not simply a matter of preference. While front matter isn't a part of the Commonmark spec, it is very well adopted to the point where it's effectively universal across blogging apps and static site generators. You can move a markdown file from Hugo to 11ty to Gatsby to Hexo to Jekyll without changing or losing any of the content and they'll all understand your title, slug, posting date, labels, etc without any configuration or code changes necessary. You lose that by doing something different even if you prefer an alternative approach. That's something to consider if you choose to go against the grain. It affects more than just preference. Personally the biggest advantage I see of front matter is that it encapsulates everything about a post in one place. I don't need to update an index if I delete a post, or add one, or something. That said, writing a script to take the index content and insert it in to the post markdown files as front matter wouldn't be very hard, just as it'd be very simple to extract front matter to your own index file, so it's not really a big deal however you choose to do things.
  - Borkdude 5y ago
    I'm not married to either one of the approaches and it's fairly trivial to switch between the approaches if I might change my mind.
  - ghostly_s 5y ago
    It seems this author has no interest in using any other blogging frameworks so why does it matter?
- Terretta 5y ago
  The project is cool, I enjoyed the walkthrough, and I like Clojure and love seeing discussions applying it in everyday use. But this particular design decision, which works well for the author, is worth flagging for others as it bumps against a variety of first principles in Unix and Lisp such as simplicity, composability, and interop/portability apart from tools. For example, from your comment: > Instead of … filenames … have an index [of] filenames to read + the metadata And now you have to sync an index of metadata on top of the existing index and files. If you interact with the files through any other tool, you can have files not in the index, or index w/o files… Plenty use cases depend on that. Here’s a user asking about inability to independently edit files with Joplin: https://discourse.joplinapp.org/t/yaml-front-matter-metadata-in-markdown-export-and-import/9384 https://discourse.joplinapp.org/t/yaml-front-matter-metadata... But here we already have an index, the directory tree, that already contains the critical metadata: name, created/modified dates, sufficient to retrieve the media and the media specific metadata. Can even natively leverage tags if we use file tag metadata natively supported in some filesystems, then the OS GUI and other apps can search and retrieve w/o extra moving parts, and still read custom metadata from the media (in this case plaintext markdown article) itself. Also, most “bog standard” markdown editors have, by now, a toggle to pretty print or table-ize frontmatter, and suppress it on publish (especially since many leverage pandoc which supports that). When they don’t, it’s just three dashes and some TOML, works fine as text. Put another way, YAML Front Matter is to plaintext .MD articles as ID3 tags are to MP3, AIFF, AIF, M4A, M4R, FLAC, OGG, WAV, APE, ASF, and WMA audio files. TL;DR: Even if you maintain a separate index, you still want to write back the metadata into the media file standard so the media outlasts the media management tool.
joppy 5y ago
It’s universal portability, but at the cost of only using the lowest-common-denominator features of any random markdown implementation. There are so so many more things that can be done with websites and long-form writing than big standard markdown, and even Pandoc (which I consider to be the most versatile fully-featured markdown implementation) has extensive support for user-written filters, which provide more on top of what Pandoc markdown provides. What is the priority - being able to switch blog implementations at the drop of a hat, or having an actually good website?

capableweb 5y ago

The bog-standard Markdown editor would output the front matter directly in the post, unless it specifically has support for front matter. So if you're really aiming for "universal portability", get rid of the front matter. And there is nothing wrong with inversing the control of the metadata. Instead of having each file carrying the metadata and you need to iterate filenames to get the full list, it's OK to have a index that has the filenames to read + the metadata. Simply a matter of preference and not really a requirement for someone to say that they "blog in markdown files", whatever that means.

onion2k 5y ago
Simply a matter of preference... It's not simply a matter of preference. While front matter isn't a part of the Commonmark spec, it is very well adopted to the point where it's effectively universal across blogging apps and static site generators. You can move a markdown file from Hugo to 11ty to Gatsby to Hexo to Jekyll without changing or losing any of the content and they'll all understand your title, slug, posting date, labels, etc without any configuration or code changes necessary. You lose that by doing something different even if you prefer an alternative approach. That's something to consider if you choose to go against the grain. It affects more than just preference. Personally the biggest advantage I see of front matter is that it encapsulates everything about a post in one place. I don't need to update an index if I delete a post, or add one, or something. That said, writing a script to take the index content and insert it in to the post markdown files as front matter wouldn't be very hard, just as it'd be very simple to extract front matter to your own index file, so it's not really a big deal however you choose to do things.
- Borkdude 5y ago
  I'm not married to either one of the approaches and it's fairly trivial to switch between the approaches if I might change my mind.
- ghostly_s 5y ago
  It seems this author has no interest in using any other blogging frameworks so why does it matter?
Terretta 5y ago
The project is cool, I enjoyed the walkthrough, and I like Clojure and love seeing discussions applying it in everyday use. But this particular design decision, which works well for the author, is worth flagging for others as it bumps against a variety of first principles in Unix and Lisp such as simplicity, composability, and interop/portability apart from tools. For example, from your comment: > Instead of … filenames … have an index [of] filenames to read + the metadata And now you have to sync an index of metadata on top of the existing index and files. If you interact with the files through any other tool, you can have files not in the index, or index w/o files… Plenty use cases depend on that. Here’s a user asking about inability to independently edit files with Joplin: https://discourse.joplinapp.org/t/yaml-front-matter-metadata-in-markdown-export-and-import/9384 https://discourse.joplinapp.org/t/yaml-front-matter-metadata... But here we already have an index, the directory tree, that already contains the critical metadata: name, created/modified dates, sufficient to retrieve the media and the media specific metadata. Can even natively leverage tags if we use file tag metadata natively supported in some filesystems, then the OS GUI and other apps can search and retrieve w/o extra moving parts, and still read custom metadata from the media (in this case plaintext markdown article) itself. Also, most “bog standard” markdown editors have, by now, a toggle to pretty print or table-ize frontmatter, and suppress it on publish (especially since many leverage pandoc which supports that). When they don’t, it’s just three dashes and some TOML, works fine as text. Put another way, YAML Front Matter is to plaintext .MD articles as ID3 tags are to MP3, AIFF, AIF, M4A, M4R, FLAC, OGG, WAV, APE, ASF, and WMA audio files. TL;DR: Even if you maintain a separate index, you still want to write back the metadata into the media file standard so the media outlasts the media management tool.

joppy 5y ago

It’s universal portability, but at the cost of only using the lowest-common-denominator features of any random markdown implementation. There are so so many more things that can be done with websites and long-form writing than big standard markdown, and even Pandoc (which I consider to be the most versatile fully-featured markdown implementation) has extensive support for user-written filters, which provide more on top of what Pandoc markdown provides. What is the priority - being able to switch blog implementations at the drop of a hat, or having an actually good website?