RE:CZ

Against Embedded TOC and Syntax Tax, Focus on Content Creation

Content Management

👤 Content creators, bloggers, Markdown users, technical writers, individuals concerned with writing efficiency and tool optimization
This article criticizes the practice of embedding TOC and YAML FrontMatter in Markdown source files, arguing that these syntax taxes distract from writing, reducing efficiency and quality. The author advocates for separating content from metadata, with tools automatically extracting and processing it to reduce syntax tax. The article also discusses desktop optimizations such as column layouts and side notes, and suggests supporting inline comment features to enhance interactivity, though it must address issues of comment positioning due to source text changes.
  • ✨ Embedded TOC and YAML FrontMatter are syntax taxes that increase source file burden
  • ✨ Syntax taxes distract from writing, reducing efficiency and quality
  • ✨ Content and metadata should be separated, with tools handling it automatically
  • ✨ Desktop can be optimized with column layouts and side notes
  • ✨ Support inline comment features to enhance content interactivity
📅 2026-01-27 · 415 words · ~2 min read
  • Syntax tax
  • Content creation
  • TOC
  • Markdown
  • Desktop optimization
  • Inline comments
  • Writing efficiency
  • CZON

It is now the evening of January 27, 2026.

Focus on Content, Reduce Distractions in Writing

After reading C1's blog, I noticed he uses embedded TOCs to generate a table of contents.

I believe this imposes an unnecessary burden on the Markdown source files.

As shown in the image below, he writes nearly 40 lines of structure and metadata before getting to the actual content.

Source Code of one article of C1's Blog

The issue is that the TOC source code is written directly into the source file. Although maintenance is likely handled by specialized tools, this fills the source file with a lot of "syntax tax" unrelated to the content. In fact, writing metadata in YAML FrontMatter is also a form of syntax tax. I strongly oppose this as well. However, YAML FrontMatter is not as visually cluttered as TOCs, so I haven't opposed it as vehemently before.

I firmly believe that once you start paying special attention to style, formatting, structure, and layout while writing, your focus shifts away from the content itself. Attention becomes scattered, affecting writing efficiency, quality, and ultimately, content creation.

When writing, a person's eyes are constantly reviewing previously written content. If the content is filled with various formatting syntax, attention is diverted, making it difficult to focus on the content itself.

In CZON, content metadata should be extracted, not embedded within the content itself. Content creators should not be forced to write this metadata. Content creation can be fragmented, with AI + Infra handling integration and layout. Reducing the "syntax tax" of writing is one of CZON's key metrics.

Mobile-First, but Desktop Can Offer More Optimizations.

Mobile devices are limited to a single-column scrolling layout, while desktop can utilize multi-column layouts. Therefore, the reading experience on desktop can be significantly better. For example, navigation bars, table of contents sidebars, etc., can be placed in sidebars, making full use of the desktop's wider screen. For desktop, footnotes could even be converted into sidenotes, similar to some large-format printed books.

For long articles, anchors are also an essential feature. Since CZON 0.6.3, automatic TOC extraction and heading anchor functionality have been supported.

More Interesting Features

For example, support for inline comments. This would allow readers/AI to add comments and discussions at any point in the article. This could greatly enhance content interactivity and engagement. Apps like WeChat Reading and WeChat Official Accounts support this kind of underline/comment interaction. The downside is that if the original text changes, comment positions might become misaligned, requiring a more stable positioning method.

See Also

Referenced By