Personally, I do not find it complex to code everything I need to do using markdown. I prefer it, I have coded many many useful things in wiki, and utilise structures that are only available in markdown. I see little cost, and some advantages.
However the main advantage is to be part of the open source mainstream of writers and coders of such writing - nearly all of whom have standardised on markdown in some form or other. It feels a good compromise to my coding practice.
Html is too far, and ascii text is too limiting. Utf8 mardown and/or json is my archetectural choice. I look forwards to hearing and understanding counter arguments in writing - all the best to learn from.
# ASCII, Unicode, and pragmatism Some engineers prefer “stick with ASCII” for maximum portability across terminals, diffs, and legacy systems. That instinct aligns well with core Markdown, which uses simple punctuation. Modern ecosystems, however, handle Unicode reliably, and typographic characters can improve readability.
Where to use ascii (practical stance): - Default to ASCII in syntax and headings. - Allow Unicode where it adds clear value (names, symbols, examples). - Enforce consistency with linters and CI so teams don’t drift.
# Mix and Match
Experiments and research indicate, but do not yet establish, that it should be possible to define an elegant markup that satisfies the needs of authors yet provides the structural elements we need for the future, in a manner that we can incrementally and optionally add to wiki and Markdown texts.
- Yam and Kson and arguments for Kson and Structure
# Summary
> Note: this is work-in-progress, and my personal take or understanding. To be deliberated in more detail and in dialogue in writing.
- Start with baseline Markdown (CommonMark + GFM). - Keep documents short, sectional, and link out for depth. - Use `plan.md` for intent and milestones; keep it living. - Store agent prompts in `.md` with fenced blocks and clear contracts. - When you need structure, attach Yam or Kson rather than inventing inline conventions. - Optimize for diff-ability and cross-tool rendering first.