19 ms·

I prefer rST to Markdown

• betaby 2y ago
  asciidoc anyone?
  • schaefer 2y ago
    I keep my journal in a blend of asciidoc and markdown. In asciidoc, I love xref soooo much, which lets you make cross-document links to .adoc files that still work after being translated to html. But I'm so sad that asciidoc isn't supported by pandoc.
    • argonaut68 2y ago
      +1. My current workaround is the use of asciidoctor to convert my docs to docbook. This format is supported by pandoc.
  • papascrubs 2y ago
    Right? So many features, and much easier to write than RST in my opinion. You can do things like dynamically reference other files to build tables: [%header,format=csv] |=== include::tracks.csv[] |=== What about only including specific lines? Say from a log file or a separate piece of code? You can do that! [source,python] |=== include::example.py[lines="1..10,15..20"] |=== Asciidoc solves nearly every problem I've ever run into with markdown and RST. I really wish it were more widely adopted.
• Aardwolf 2y ago
  Ignores newlines (turns single newlines into spaces) so just as annoying as markdown for me. I'm looking for a text format that has some formatting ability, but preserves newlines you enter. BBCode is a good one. What makes so many designers of these plain text formatting languages choose to not preserve newlines? I don't get it. Preserving newlines is one of the main features of plain text. This causes the same annoying thing as hacker news comments do, like this intended multiline shopping list: -eggs -flour -milk -sugar -salt
• louwrentius 2y ago
  The one-line summary is: > I think Restructured Text is better for writing books than Markdown. That would be a better title.
• PaulHoule 2y ago
  I was looking at RST as an answer for a documentation system with similar complexity to the system he's building and an intense need to mark stuff up with definite semantics, both in the case of capturing structures in the RST file in a database and mixing database results into the content. Two problems I had were: (1) common with a lot of systems, the RST tools don't contain an RST unparser. I really wanted to be able to generate RST files automatically by merging content from other RST files and other sources and working with them via a document API. The RST tools don't support that. (2) The RST tools expect a certain defined set of blocks for a particular document; it would be very possible for a system to represent blocks in a generic way which would make possible tools that can transform documents without necessarily knowing the definitions of blocks inside it. These are problems w/ the tools, not problems with RST itself but every time I'm forced to strip my code back to the walls is an opportunity to think about some other markup system such as something HTML-based.
  • zdw 2y ago
    I don't think this is the case. In python, rST is just one of many supported input formats for docutils: https://docutils.sourceforge.io/README.html#purpose https://docutils.sourceforge.io/README.html#purpose The entire point docutils is to parse formats and convert using an API: https://www.docutils.org/docs/index.html#api-reference-material-for-client-developers https://www.docutils.org/docs/index.html#api-reference-mater...
    • PaulHoule 2y ago
      My beef is that it doesn't have an RST writer. What I want is a central hub where I can suck in documentation that was originally in different formats and then manually edit it in a format where I can capture essential semantics and then feed it through the system again to produce output documents. If it had that it would be a 200 foot tall giant robot, as it is it's just another documentation generator.
      • zdw 2y ago
        Ah, you want something like pandoc, but you can manipulate the internals as needed?
• benji-york 2y ago
  I lament the lack of rST support in much of modern tooling. I'm reminded of all of the alternate worlds that didn't quite come to fruition, but could have (Lisp, Smalltalk, BeOS, etc.).
  • bunderbunder 2y ago
    An interesting commonality among the three examples you listed: they're all designed for a world when computing was a more solitary activity than it is now. For Lisp and Smalltalk, image-based development is a genuine hurdle in the modern world. It complicates many aspects of modern highly-collaborative software development, including version control and continuous integration. I think that the language's respective hacker ethoses might also be a challenge in light of how often people switch jobs nowadays. I haven't used Smalltalk for pay money, but my experience has been that initially getting settled into a large pre-existing Lisp project does take more brain effort than it seems to with a language like Java. (In the long run I'd rather inherit a Lisp project, but I also acknowledge that first impressions are important.) And BeOS was not a multiuser OS and didn't seem to have a clear path to becoming one. I'm pretty sure the main thing preventing it from becoming as much of a cybersecurity disaster as Windows 95 was is the simple fact that there wasn't any honey in that pot.
    • marcosdumay 2y ago
      Image-based development was never good. So we pushed it back again and again, so that we nowadays have a single image component we named "database" and most of the work is free from its problems. That doesn't mean we stopped doing it.
  • Macha 2y ago
    This largely occurs because the only real spec of rST is the Python implementation. And tools written in other languages are loath to include a Python library just to support one document format. While writing a new compatible implementation is much more work given the larger scope than it is for Markdown. So every language has a markdown implementation, but if you want to use rst in your Rust based static site generator or your PHP based CMS or whatever, it's a lot more work.
• deleted 2y ago
  [deleted]
• jawns 2y ago
  > markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree To me, the whole point of markdown is to allow you to do simple things faster than writing raw HTML, but with the ability to intersperse raw HTML when needed. In projects where I've needed the power of RST over markdown, I've felt more comfortable just writing raw HTML directly.
  • strongpigeon 2y ago
    That’s pretty much how I feel. When the author writes: > This means you can extend Sphinx with new text objects! Say you that instead of an <image>, you want a <figure> with a <figcaption>. In basic markdown you have to manually insert the html I can’t help but wonder what’s wrong with just writing HTML if you want those features? Why the extra layer?
    • scott_s 2y ago
      The author wrote an entire article explaining their use case which answers your question. Short version: they’re writing a book which they want to render to multiple formats with semantic linking between items and different rendering based on formats.
      • strongpigeon 2y ago
        I get that, but why not use HTML as the base to render to other formats? I guess I'm not 100% clear what you mean by semantic linking and how could that not be achieved through HTML.
        • scott_s 2y ago
          If I understand you correctly, you want to throw out rST, and just have users write HTML directly? I see two issues with that: 1. HTML is designed for representing webpages, not books. Your intermediate representation will become HTML's DOM, which is likely not well suited to the book use case. You'll either need to use an existing HTML-to-DOM parser or build your own. One big limitation of the DOM, as I see it, is that it doesn't have the concept of a page number. 2. HTML is not extensible in the way the author talks about. This is the "semantic linking" thing I meant. In rST, you can define entirely new top-level constructs: he defines an exercise which has a solution and will be a part of a solution list. The semantic linking part is that other parts of the document will refer back to these solutions. Some output formats will have all solutions inline, with the exercises, while other output formats will collect all solutions in one place at the end. HTML is not flexible in that manner. What is extensible is XML. It's entirely feasible for XML to be the input, but for better-or-worse, most people are even more turned off by XML than they are by something like rST.
• teamspirit 2y ago
  Isn’t this just a case of different tools for different jobs (or the right tool for the right job)? Rst clearly has some advantages for this use case but, at least for me, markdown is much faster and clearer to understand when jotting down my daily notes.
  • hwayne 2y ago
    Absolutely. I prefer rst for the use case of writing a technical book, because of the specific benefits I get from its additional complexity. My blog is still in markdown.
  • bluGill 2y ago
    Having done a little of both, I find RST is faster just because I can lookup whatever syntax I need to keep going while with markdown I often stop to scream because I can't make it do what I want. Either is easy enough to understand when reading raw text - this is mostly about good style though, RST gives you more options for bad style that is hard to read.
• BerislavLopac 2y ago
  > markdown is a lightweight representation of html This is my main problem with the article, as this is decidedly incorrect. Markdown was designed as a tool of conversion of de facto standard of formatting text in email messages and Usenet posts of early nineties. The basic 7-bit ASCII nature of those technologies inspired people to informally annotate the text with special signs to denote formatting like emphasis, section titles and the like. True, HTML shares a lot of similarities with that nameless standard, so John Gruber in 2004 wrote a basic script [0] to convert the latter to the former, never expecting it to become such a universally used actual standard. [0] https://daringfireball.net/projects/markdown/ https://daringfireball.net/projects/markdown/
  • simonw 2y ago
    I disagree. Markdown has always been about HTML - to the point that Markdown parsers support dropping actual HTML tags mixed in the the markup. The fact that Markdown was inspired by email conventions doesn't make the statement "markdown is a lightweight representation of html" any less correct.
    • SoftTalker 2y ago
      I thought a goal of Markdown was to be a set of conventions that were readable on their own as well as being transformable to a rich text/HTML representation. You can read a Markdown document pretty easily using "less" or any other character-based interface. The same is not really true of reST. Maybe I'm confusing that with some other plain-text markup convention?
      • paiute 2y ago
        The article convinced me that markdown is better for its purpose.
      • Spivak 2y ago
        reST is also designed to have human readable source. You might not like it compared to markdown but it has to serve as a the docstring format of Python and does so fairly well.
• simonw 2y ago
  A few years ago I wrote up some notes on the subset of reStructuredText that's worth committing to memory: https://simonwillison.net/2018/Aug/25/restructuredtext/ https://simonwillison.net/2018/Aug/25/restructuredtext/ I've started using MyST for my more recent projects, which gives me the features I care about from reStructuredText - references and table of contents - but lets me use markdown syntax, which is easier for contributors.
  • smore 2y ago
    Great points about links, especially external links — it makes a lot more sense in the context of a documentation site where you might have the same external link referenced multiple times in the site, but you only want to have to update it once if it changes. The real gamechanger is for internal links (rST+Sphinx) and the use of the `:ref:` and `:doc:` directives so that you can reference an anchor or a doc link in the same content without having to type the header manually (which will inevitably go stale). https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role https://www.sphinx-doc.org/en/master/usage/referencing.html#... that is one of the things I miss most about writing in rST, for sure.
• jasonpeacock 2y ago
  Lemons vs limes. They're both markup languages, but they have different purposes. Yeah, using markdown to write a book is very limiting and doesn't offer the control needed for typesetting. OTOH, using markdown to write is liberating - you only get a few markup options, so you can focus on the content: [It is] notable that the Feynman lectures (3 volumes) write about all of physics in 1800 pages, using only 2 levels of hierarchical headings: chapters and A-level heads in the text. It also uses the methodology of sentences which then cumulate sequentially into paragraphs, rather than the grunts of bullet points. Undergraduate Caltech physics is very complicated material, but it didn’t require an elaborate hierarchy to organize. Edward Tufte, forum post, ‘Book design: advice and examples’ thread
• Karellen 2y ago
  Any sufficiently complicated lightweight markup format contains an ad-hoc, informally-specified, bug-ridden, and only slightly easier to use implementation of half of either DocBook or TeX.
  • nequo 2y ago
    Yes but Djot is pretty good though! Wouldn’t call it informal nor bug-ridden, it’s well thought out and doesn’t have many corner cases: https://djot.net/ https://djot.net/ Designed by one of the authors of CommonMark, an attempt to specify a standardized flavor of Markdown.
    • 0cf8612b2e1e 2y ago
      I just wish it would move along already. I get it, some tough calls need to be made on edge cases that do not have a correct answer. Yet I want a 1.0 release so I can feel confident that the language will have staying power. Then again, it is already in pandoc, so I suppose you can trivially move out of it.
    • keybored 2y ago
      Djot insists that this nesting of bullet points is wrong: - first - second Instead you need this: - first - second I’m very picky about the aesthetics of lightweight MLs so this is tough to swallow. EDIT: By the way, recent comment from the primary developer: https://github.com/jgm/djot/discussions/310#discussioncomment-10182767 https://github.com/jgm/djot/discussions/310#discussioncommen...
      • kps 2y ago
        Not having used djot myself, does “rethink tight/loose lists” refer to that?
  • the__alchemist 2y ago
    Indeed; Github will now render TeX in markdown documents, eg when displayed as a repo's readme. Very convenient.
• breck 2y ago
  Here is how you would do your image example in Scroll: rst: .. image:: example.jpg :alt: alttext scroll: image example.jpg caption alttext "Directives" in rST are "Parsers" in Scroll. The item above would be parsed by the `imageParser`, which at ~50 lines of code (https://github.com/breck7/scroll/blob/b8fd72aa38742cc6cd575fa57aa764d0b35a44a7/parsers/images.parsers#L25 https://github.com/breck7/scroll/blob/b8fd72aa38742cc6cd575f...), is actually more code than the average parser. To write your "exercise extension" in Scroll, you would just need to write a few lines of code definining an "exerciseParser". You could put that in the same file you use it in, or in a file named "exercise.parsers". I think you should explore Scroll -- https://scroll.pub/ https://scroll.pub/ -- might do everything you need in a simpler way!
  • eviks 2y ago
    Out of curiosity, would you be able to write a parser that uses the markdown style for image links?
    • breck 2y ago
      Yes, you could do that. At some point soon (perhaps this already works today), you could probably just copy/paste the entire Scroll Parsers code (https://try.scroll.pub/scroll.parsers https://try.scroll.pub/scroll.parsers) into a ChatGpt or Claude.ai prompt and ask it to write one.
• bluGill 2y ago
  The problem with RST is the same with everything else: it isn't supported everywhere. I wrote a bunch of nice RST documentation at work, the next month some company wide team announced a new standard for documentation (backstage) which is markdown based, and has all the problems of markdown. (In their defense I'm not aware of any tool that would compete with backstage for what we need in a company wide documentation system)
  • f1shy 2y ago
    One solution: https://pandoc.org/ https://pandoc.org/ Or “how I stopped caring about doc formats”
• morbicer 2y ago
  RST might be technologically superior but markdown is easy to write and has a huge ecosystem. For hobby usage, use whatever. But I would strongly oppose anyone who would try to make RST standard at my workplace. A scrum-master, PO or marketing can write markdown. RST would be a hard sell.
• numlock86 2y ago
  > markdown is a lightweight representation of html Never before on an article I've felt the vibes of the "I stopped reading there"-meme harder than here.
• psychoslave 2y ago
  >The most important difference between rst and markdown is that markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree. Not really. Quoting https://en.wikipedia.org/wiki/Markdown https://en.wikipedia.org/wiki/Markdown >Its key design goal was readability, that the language be readable as-is, without looking like it has been marked up with tags or formatting instructions, unlike text formatted with 'heavier' markup languages, such as RTF, HTML, or even wikitext So, for use cases that don’t make a good match of this chief constraint, Markdown might not be the most relevant option. It’s just as meaningful as saying that we prefer TeX over Markdown because fine typographical tuning is an important concern of our specific usecase. I admit I already dealt with a screw using a hammer, not having the right toolset at hand. But when the situation don’t call for adhoc heterodox actions, I prefer to match a screwdriver with a screw and a hammer with a nail.
• queuebert 2y ago
  Personally, besides it being a nice format, I use Markdown to honor Aaron Swartz.
  • Ericson2314 2y ago
    Haha on one hand its probably Aaron Swartz's worst work. On the other hand, this is definitely the best reason to use markdown. RIP
• mg 2y ago
  Markdown:  RST: .. image:: example.jpg :alt: alttext The author prefers RST because: ... you can extend Sphinx with new text objects! Say you that instead of an <image>, you want a <figure> with a <figcaption> ... What I would do: [caption] And write a renderer which supports this syntax to create a figure with a figcaption. A markdown renderer is simple enough to write your own or extend an existing one.
  • eichin 2y ago
    Exactly - does anyone (well, maybe the author does since he did use markdown in previous works) use "basic" markdown anyway? There are always some extensions (either front-text metadata or syntax extensions like this one) in the "interesting" apps. (The python markdown module API kind of feels like it's entirely about extension and only a little bit about actually parsing, but that did make it easy to add an `ASIN()` token for a review site without needing a preprocessing stage...) That does make it a little worse for interchange, but that's maybe less important for markdown anyway.
    • eichin 2y ago
      (Even with pandoc, https://pandoc.org/MANUAL.html#extensions https://pandoc.org/MANUAL.html#extensions lists a bunch of syntax for things like this, brought in from github, php, and other places - for the example above, `implicit_figures` and `link_attributes` are a good starting point.)
  • Ericson2314 2y ago
    OK that specific example works, but what about his later problem vs solution one? One runs out of hacks pretty quickly.
  • romanovcode 2y ago
    Honestly I stopped reading article after this example. No, thank you. RST syntax looks confusing and overly explicit. I'd stick with MD thankyourverymuch.
• smlavine 2y ago
  I think commenters are missing that the author is talking about this in the context of typesetting their own book. They aren't claiming that rST is better than Markdown in the general case; in general, Markdown's simplicity is a reason why it is so widely used. But that's not what the author is talking about.
  • justin66 2y ago
    [flagged]
    • jerf 2y ago
      Well, the simple mental hack for yourself is just to prepend all blog content, if not all content in general, with #include <general_disclaimers> and you'll find yourself much happier in life. Speaking as one who actually produces blogs on rare occasions, I have to say starting every post with "This is just my experience and may not apply to you this is not a claim of global applicability this is just applicable to this circumstance you're the one who chose to read this I didn't force you" and so on isn't exactly the most compelling way to open a post. Though I have to admit now I'm really tempted to add that into my post template in like 2pt font or something, just so when people on HN complain I can point them at it.
      • justin66 2y ago
        But that's all beside the point - we're not talking about a "general disclaimer." (I am intrigued by how blurry the lens you look at the world must be, if you live by that "#include <general_disclaimers>" nonsense) People interested in the blogger's rather specific Markdown use case would be better served by a more specific title, as would the nine out of ten Markdown users who are not.
        • jerf 2y ago
          No, I was just recommending it to you since you seem to be perturbed. I just give people a general measure of grace in their writing and it all seems to work out fairly well. You can try that as well, if you like.
• blt 2y ago
  If the author is here: Before the first code display, where you write: > Here's how to make an image in html: I think you meant "markdown" instead of "html".
• tristor 2y ago
  I use Markdown constantly, every single day, and I have tried multiple times to switch to RST and failed. Ultimately the reason Markdown works the best for me is that it gets out of my way. I can just type, I don't have to invest significant effort in formatting structures and can just write. This makes Markdown ideal for my primary use case, which is note-taking live during meetings, and because I already use it there, I also use it for writing blog posts, documentation, and most other document writing purposes. I will freely acknowledge RST is better for writing documentation and formal structured documentation, but the learning curve/barrier for RST is enough higher than Markdown, that it's not worth it for me to use both systems.
• mjburgess 2y ago
  I believe the big selling point is supposed to be the directives syntax of rST. I had a similar need to extend markdown, but pandoc already supports directive syntax -- and so do some libraries, eg., the marked library, which I use to render MD as HTML in-browser rather than with pandoc. The iirc, syntax is :inline{property} and ::: block-directive {options} contents ::: It doesnt nest well, so I applied any document-level styles using the filename; but I'd imagine the yaml-style lead-in tags should be the correct way to do it.
• kaycebasques 2y ago
  Context: I've been a technical writer for ~12 years. I actually started out my career migrating a startup's docs from Word to Sphinx. Then I did a lot of time on Google's proprietary CMS/platform for developer docs. Then a few years on Eleventy-based sites. For the last two years I've been back on a Sphinx-based site (pigweed.dev). I've also done some odd jobs for readme.com-based startups and have dabbled in Docusaurus, Astro, and Hugo. reStructuredText (reST) by itself can be pretty rough. reST combined with Sphinx is pretty great. I.e. the strengths of Sphinx far outweigh the weaknesses of reST. For big, professional docs sites (+100 pages, +10 contributors) I have pretty strong opinions that Sphinx is probably the most responsible choice, long-term. > The most important difference between rst and markdown is that markdown is a lightweight representation of html, while rst is a midweight representation of an abstract documentation tree. Yes, what this means in practice is that it's easy to customize common aspects of your site (such as how images are displayed). A teammate of mine on Pigweed recently created a shortcut for linking to bugs consistently. You type :bug:`59385981` and the link gets transformed into https://pwbug.dev/59385981 https://pwbug.dev/59385981. If we ever need to mass-migrate all of our bug links, it's now trivial. Another profoundly important consequence of this architecture: all internal links are guaranteed to always resolve (you get warnings/errors if you link somewhere that doesn't exist). I previously wrote about how baffling it is that this is not the industry standard for docs sites: https://technicalwriting.dev/src/link-text-automation.html https://technicalwriting.dev/src/link-text-automation.html The other thing that Sphinx excels at: well-defined extension and theme APIs. It's not exactly easy to build extensions or themes, but lots of people have figured it out (including me). There's a pretty rich ecosystem of extensions and themes on PyPI. Lately I've been calling Sphinx the sleeping giant of docs systems. It's already pretty great and with a little concerted effort I think we can collectively make it absolutely phenomenal. The upstream Sphinx repo now has a GitHub Discussions section that gets a little traffic; a lot of us seem to congregrate on the #sphinx channel in the Write The Docs Slack.
  • thechao 2y ago
    I did not know about Sphinx until your comment (I'll get to my 2-day delay in response, briefly). I've been doing technical writing "on the side" as my dev work allows, for 20+ years. I've been a TeX/custom-XSL sort of dude the whole time. I just ported a 200+ page book documenting an internal language/VM/abstraction-layer to Sphinx ... holy moly, this is a life changing system! I wish the documentation for Sphinx, itself, had a lower ramp and/or more examples; otherwise, I'm still in a pretty fantastic honeymoon phase. My two main lines of research are how to build good looking PDF (books); and, some sort of system to let me cut a book into POSIX compliant man pages by chapter/section.
• kelsey98765431 2y ago
  When you call a book v0.2 and say "now with epub, get it here" in the first line of your blog on why not to use the most popular of a thing, I am assuming we are going to be having a above board conversation about pros and cons, and I an receptive to your position. When the first link is also the second link, and both are to BUY a 15 dollar book with the default "pay anything price" bar set to 20, I am just clicking out and ignoring literally everything in your marketing post. Others can discuss this RST thing I have never heard about, I am just here to point out you have now alienated one of your potential converts. Put the book link at the bottom, and dont double link to the same purchase page in the same paragraph. FFS.
• joekrill 2y ago
  The thing I like about markdown is that it's very readable as just a raw format. With the bonus that it's easily converted to HTML. But it doesn't need to be converted to HTML. I guess this sort of falls under the "But I hate the syntax" section of the article, but I don't think it quite gets the point. I can look at a Markdown file and read or write it without even really thinking. Which is not really the case with rST (or even HTML, for that matter).
  • bluGill 2y ago
    I can look at a rST file and read it, and I think you will have no problem reading every rST file I've ever looked at. Sure it will take you a few seconds to realize you can ignore various syntax things, but that isn't a big deal and then the whole makes sense. Of course rST gives a lot more options to write documents that are not human readable, but it isn't that hard to make them readable.
• prpl 2y ago
  Sphinx + markdown (Myst) is a nice middle ground here I think, with the sphinx directives implemented as code blocks.
• deleted 2y ago
  [deleted]
• karaterobot 2y ago
  I thank the author for explaining their reasoning. I still disagree, but I appreciated reading the argument. Apart from the ugliness of the syntax from a devex perspective, I think one of the big advantages of Markdown is that it's highly readable even without being interpreted, which rST is not. So if you have a markdown document and no markdown interpreter, an average person can still make more or less perfect sense of the contents, including the hierarchy and emphasis.
• Morizero 2y ago
  > You just need a regex to transform it into <img alt="alttext" src="example.jpg"/>. Is this what the author means by markdown being lightweight, since the inverse isn't true except trivially?
• insane_dreamer 2y ago
  I would say which is better depends on the use case. For note taking and most simple documents, Markdown wins hands down due to its readability and speed. For complex document sets where custom rendering may be required, rST+Sphinx is probably what you want.
• thesnide 2y ago
  Rst is technically vastly superior to MD. Yet I predict that MD will prevail. VHS style. I hugely prefer to write in RST, but as soon as I'm not alone we always switch to MD, given enough coworkers.
  • 12_throw_away 2y ago
    Yep, it seems like the platonic ideal of a "worse is better" situation. I do think this is, ironically, partly a documentation problem - when I last tried to create docs for a python codebase (several years ago), I found the rST docs to be sorely lacking in basic, introductory "here are the core mental models for how this works" sorts of content. Maybe the situation is better now? (Or maybe I just missed them, but not for lack of trying) But I feel like then, it's obvious README.md prevailed and will continue to be the standard - you can use markdown for a very long time without ever reading any documentation at all. Worse is better, I guess.
    • bloopernova 2y ago
      In my opinion, I don't think it's "worse", just simpler. Plus it's more ubiquitous, supported by Github etc etc. Although Github may not be the best yardstick there, because they render documents written in Emacs' org-mode too! (which I very much appreciate, I prefer writing in org to writing in Markdown) I'm hoping that LLMs will make it more streamlined when documenting existing code. Not so much as a replacement for text written by experts, but in converting code into diagrams. LLMs or similar "understand" a codebase by tokenizing it (as is my understanding), so turning that into a nice documentation skeleton should be possible.
• paxys 2y ago
  IMO the most important feature of markdown is that any random person, whether they are technical or not or know what markdown is or not, can view markdown-formatted text and understand it perfectly fine. A UI layer added on top is nice to have, but not at all necessary. Most alternative formats miss that critical point.
• IshKebab 2y ago
  I would strongly recommend using Asciidoc over Restructured Text. Even though Asciidoctor is written in Ruby which IMO is much worse than even Python, the actual RST codebase is a total incomprehensible mess. You can extend it with custom processing etc, but... fuck, I really want to never have to do that again. Asciidoc just seems to be much higher quality in general.
  • jszymborski 2y ago
    I echo your sentiments, but sadly the Asciidoc python compiler (as far as I can tell) is deprecated and no longer supported. I think that leaves Asciidoctor as the only mature compiler. There's a spec being drafted, so hopefully that will spur some more action. For my purposes, Asciidoc is the best markup with the worst tooling, and Markdown is the worst markup with the best tooling.
    • 60secs 2y ago
      the toc macro on asciidoc is sublime :table-caption!: :toc: macro :sectlinks: toc::[]
    • FartinMowler 2y ago
      I run asciidoctor's Docker container. It does what I want it to do without leaving a mess behind on my laptop.
      • IshKebab 2y ago
        The trouble with that is it becomes a pain in CI. Nested Docker isn't fun.
    • IshKebab 2y ago
      Yeah a nice Rust or Go-based implementation of Asciidoc would be fantastic. Having to deal with Ruby and Gems is not fun. That's a mountain of work though and even if there is a spec, at this point it's complex enough and the Ruby implementation is enough of a de facto spec that I'm doubtful you'll ever make it past "this behaves differently to Asciidoctor" territory. Btw a more recent alternative is https://github.com/jgm/djot https://github.com/jgm/djot which actually does have multiple implementations and looks like a way better option than Markdown, but maybe not as powerful as Asciidoctor still. I haven't tried it.
• keybored 2y ago
  A lot of lightweight markup languages get the basics right (except MediaWiki). Then eventually when it comes to making extensions—and especially if it is supposed to be terse, or look it—people get into the game of strategizing ascii symbol use (maybe `!` for images, maybe `@` for a figure). At some point (and Rst[1] has a tendency to look like this, but only a little) it can start to look like some alternative, less regular markup language. Maybe you just use more backticks rather than angle “brackets”. Or maybe you have (like previously stated) marshalled all the ascii symbols so that all the common stuff can have a terse representation. Maybe they should just make a regular-looking markup for the unusual cases/user defined things. They could do something like Pollen with its Latex[1] syntax inspiration. [1] Initial caps for proper nouns
  • samatman 2y ago
    Words are styled the way they're styled. McDonald is a proper noun with two capital letters, Mcdonald is simply not correct. I'll note that you didn't manage your footnote consistently, since you spelled MediaWiki correctly, rather than spelling it wrong as Mediawiki. For some reason, you decided not to do that with rST and LaTeX, without explaining why. Latex and LaTeX aren't even pronounced the same way, so I fail to see the purpose in your (inconsistent) stylistic choices here.
    • keybored 2y ago
      I can make concessions for names that are based on real people. I assure you my mistake was not because of good-intent towards Media[Ww]iki.
      • samatman 2y ago
        What I'm not understanding is why you've invented an incorrect rule for the English language and cited it. What purpose does this serve?
  • xigoi 2y ago
    Why is your username not capitalized, Keybored?
• wodenokoto 2y ago
  I like writing markdown because it is so simple, but I agree with the author that it is too simple for more advanced stuff. But at the same time, I find the writing experience for more advanced stuff too poor. The author talks about references, but do we have a language server that can look up available references, headlines, figure names etc and help you auto complete? That’s what would make me take the plunge to a more advanced system.
  • smore 2y ago
    > do we have a language server that can look up available references, headlines, figure names etc and help you auto complete? That would be a total gamechanger! Having the ability to do ref/doc links and not have to worry about stale topic headers is another thing I loved about writing in rST that I miss now that I'm back in markdown.
  • hwayne 2y ago
    Yeah, the rst lsp server (esbonio) can autocomplete and jumpto references in your project. I believe the markdown lsp can do this too, but only to a limited extent.
• Ericson2314 2y ago
  I am proud to say this is might be the first time I finally agree with Hillel Wayne and something (at least mildly) controversial.
• Analemma_ 2y ago
  To me rST targets such a narrow middle band of scenarios that I can't see any compelling reason to use it. For simple documents where Markdown is enough, I'll use that, and if I need more layout configuration and control I'll use LaTeX or HTML. What is rST for?
• xixixao 2y ago
  This is why MDX rocks. It doesn’t have all of this builtin, but you get a lot of the same benefits.
• somat 2y ago
  "markdown is a lightweight representation of html" No, markdown is a set of standards around transforming a good looking text file into a rich format(this is usually html, but it does not have to be). The most important part about markdown is that it is a "good looking text file". If a markdown extension does not result in good looking text it has failed the one point of markdown. This is why markdown editors leave me confused, the whole point of markdown is to write a nice looking plain text document, if you are going to use a specialized editor why not use a better format? Note that markdown is a terrible document format, with only vague presentational cues and no semantic ones. it starts to suck real quick. However, it is a great idea if you want a good looking plaintext document. People understandably keep trying to "fix" markdown with better semantic options but these by and large miss the point of markdown leaving a ugly document. So RST may be the best thing since sliced bread, but it is not really in the same category as markdown, the plaintext for one is decidedly ugly.
  • Ericson2314 2y ago
    Sure, the markdown AST is its own thing, but no doubt its a isomorphic to an obvious subset of HTML and that's not a coincidence. Moreover, you are missing Hillel's second point, which is that there is nothing like an "abstract node" syntax which can be used for custom extensions. Lisp has (NAME ...) and XML has <NAME>...</NAME>, and these are separate from the choice of NAME. (GitHub-flavored) Markdown's one extensible thing is ```NAME ``` but this isn't so useful because the inside is unstructured text (on purpose). You want a custom node which doesn't escape everything within, so you can have more regular or custom nodes on the inside.
• smore 2y ago
  Markdown has a great linter in markdownlint. When I worked in rST, I found the syntax to be super extensible, and tables much easier to write (list tables! amazing!) but without an effective linter, writing in rST was consistently painful. Whitespace has meaning, so I had to set up all sorts of indent highlights and dots for each space in my IDE to try to avoid screwing up the syntax inadvertently. rst-lint and others exist, but don't seem to be maintained, and didn't seem to have documentation about how to add support for custom directives (which are definitely one of the key advantages of rST). I'd write in rST again, but without an effective linter to stop me from making easy mistakes, I wouldn't be happy about it.
  • SparkyMcUnicorn 2y ago
    I believe Mozilla uses rstcheck for linting, and it's actively supported. https://github.com/rstcheck/rstcheck https://github.com/rstcheck/rstcheck
• Animats 2y ago
  If you want all that extensibility, use TeX or something similar. Or write HTML yourself. Markdown was supposed to be simple. Yes, you can't do everything you can do in HTML. That's the point.
• pradn 2y ago
  I was thinking of how to setup a simple static blog without the baggage of a full-blow framework. Of course, I'd be re-inventing the wheel, but at least it'll make sense to me, personally. What I came up with: * Each page gets its own folder. * An optional METADATA file in each folder has stuff like the type of the page (blog post, photo gallery, code listing). * The index file can be in Markdown or rST or something. I'd just branch to a different parser based on the file name suffix. This is simple and lets me evolve the blog over time. For a personal blog, an ideal mix might be just branching to a different HTML converter based on the
  • vunderba 2y ago
    I have a customized version of pelican which is a python based static side generator. It basically supports this type of structure, except that in place of a physical separate meta-data file all the metadata goes in the front matter section at the top of the markdown file, and it gets stripped out of the actual rendered HTML.
    • pradn 2y ago
      That makes sense. The only reason to separate the metadata out is to avoid having to parse the main content files for front-matter. Plus the metadata files themselves could be in several formats, if necessary. I don't see a great need for that, however.
      • lmm 2y ago
        Hugo/Jekyll/etc. all work the way GP described too.
• photonthug 2y ago
  I’ve done this thing a few times where I have a nice layout of about 5-10 pages of markdown docs, themselves rendered from more dynamic jinja templates, and feel that life is pretty good. Looks great, got a real build process for auto docs, but too big for a monolithic GitHub readme. Now the pain starts. GitHub’s own docs for project pages don’t work. Do I need a .nojekyl file, are gh-pages branches still required? Is there a config error in the repo or did changes just not prop? I guess I’ll try actions. Fast forward a few hours and this is getting unreasonable, haven’t looked at read the docs in a while, let’s see if that works. Ok it’s being weird and wants sphinx maybe, let’s get sphinx to work with markdown, ok cool. The build works but the page width is broken after deployment even though I can’t reproduce on my machine so it must be the ads injection on the community tier. I know all this is working fine for lots of projects and have done it myself in the past. It works after it’s working. But it’s all so unbelievably fiddly. Bottom line, Markdown vs Rst isn’t even a choice/pain point on my radar, it’s more down to finding that good fit for medium sized docs projects / static hosting.
  • paholg 2y ago
    Have you looked into mdBook? I haven't used it myself, but I've enjoyed the documentation of many projects that do and it seems really nice once you get past the point where a single readme file works well. They also have some nice instructions on automated deployments. https://github.com/rust-lang/mdBook https://github.com/rust-lang/mdBook
    • photonthug 2y ago
      Thanks, but this does not seem to involve hosting? What I'm saying is, static site generation is no problem at all, because even without all the choices for frameworks, pretty much everyone has to speak at least one templating language and read/write both markdown and rst anyway. But it's surprising that writing your project docs and rolling your own static-site generator is faster than figuring out github-pages and/or readthedocs hosting from scratch. For hosting static sites, I actually like AWS amplify, and integrating it with github seems currently easier and certainly more flexible than trying to use github pages. But I don't really want the hassle of a custom domain or a subdir on existing inappropriate domains for every new project I start. This isn't about being cheap either BTW, I think it's important that self-hosting should NOT be the best way to get a friction-free setup for small-to-medium sized project docs. There's a major benefit just to the recognizable domains for github-pages / readthedocs, which is that I know I'm about to look at some kind of technical project documentation that is most likely a labor of love, rather than marketing fluff or a "sign up for the preview here!" bait and switch.
• runningmike 2y ago
  Everything you can do with rst can be done now with markdown. But easier and better. The toolchain is superb now. MyST extends Markdown for technical, scientific communication and publication - https://mystmd.org/ https://mystmd.org/ and use Jupyterbook, which builds upon spinhx.
• JoshTriplett 2y ago
  I do appreciate that reStructuredText is extensible and Markdown (currently) isn't. I don't think that's an argument that outweighs rST's verbosity. But I do think it's an excellent argument for adding a standard extension point to Markdown.
• osmarks 2y ago
  I solve this for my usecases with custom Markdown rendering which accepts a few new block elements (via a markdown-it plugin). https://github.com/osmarks/website/blob/master/src/index.js https://github.com/osmarks/website/blob/master/src/index.js
• KronisLV 2y ago
  I like Markdown because it's simple and doesn't give me that many headaches. You know what I don't like? HTML, for user submitted content in particular. The mess I've seen, after someone opted for using HTML for messages in a system, because that's what JS based editors were available for at the time. Endless need to work against XSS, with more and more incremental updates needed to the sanitization logic, some of which broke the presentation of the data in the DB. Never again. Markdown, BBCode, anything but that. As for docs? Currently just some Markdown, because that's what GitHub, GitLab, Gitea and others all know how to render. Maybe something like https://www.mkdocs.org/ https://www.mkdocs.org/ for the more standalone use cases.
• 8organicbits 2y ago
  > it's that simple markdown is exceptionally bad. It doesn't have a uniform extension syntax or native support for pre-render transforms. I feel like "simple markdown" is a straw man here. If you're doing anything complex with markdown you're going to pick a flavor and learn it. Many flavors of markdown can do the things described. Here's a Hugo figure which looks easier to understand than the "ugly rST" equivalent: https://gohugo.io/content-management/shortcodes/#embedded-shortcodes https://gohugo.io/content-management/shortcodes/#embedded-sh...
• RomanPushkin 2y ago
  No offense, but when I downloaded a sample PDF I expected to see a better formatting. The file is little bit clunky. I think it's not a failure of a formatter, but the design in general. The default markdown formatter in Leanpub works good enough, to a degree when I don't need to think about it. So, while I understand all the good parts, I am still kinda not convinced it's a better option looking at the final product.
  • hwayne 2y ago
    No offense taken! Sphinx gives a lot of options for customizing pdf formatting, but I'm not thinking about that just yet. Step one is to get the book's content done, step two is to revise the content, step three is to revise it again... Getting it to look good is on my list, but ultimately a problem for future me.
• meribold 2y ago
  Wasn't reStructuredText the one where you can't make text a link if any of it is bold/italic/monospaced? IIRC, nesting of inline markup is generally not possible. It works in Markdown…
  • hwayne 2y ago
    Yes, and this sucks.
  • remram 2y ago
    I had to scroll way too far to find this. All the arguments for RST are about how much more expressive the language is, how much care was taken in making it an abstract document tree. Yet there are simple trees you can't encode, even common ones that markdown handles fine. I'm not using a language simply because it was aiming at something better, if it missed the mark.
  • xigoi 2y ago
    > IIRC, nesting of inline markup is generally not possible. It works in Markdown… How do you write <i><b>x</b>y</i> in Markdown (without using HTML tags)?
    • meribold 2y ago
      Maybe Markdown doesn't allow arbitrary nesting of inline markup, but the combinations I actually wanted so far work. With reStructuredText, OTOH, I ran into limitations even though I didn't try to commit typographic atrocities.
    • remram 2y ago
      _**x**y_ works fine, I tried on GitHub: https://gist.github.com/remram44/8cd460aef9020aa53d538b82cb40bd9f https://gist.github.com/remram44/8cd460aef9020aa53d538b82cb4...
      • xigoi 2y ago
        Oops, I forgot that underscores are a thing :D
• Arainach 2y ago
  >To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?" Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant. Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax. I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.
  • michaelcampbell 2y ago
    If you'd read past that, the author says "yes, those are good reasons, I would too".
  • pclmulqdq 2y ago
    I am probably in the 90th percentile of TeX users, but I have to say that it's hard for me to think that there's much space between markdown and TeX for another typesetting language. Markdown is easy to write and read but very constrained, while TeX is a bit harder and essentially infinitely flexible. The biggest issue I have seen with TeX is a people problem: people frequently write spaghetti TeX with horrible style. This is terrible, but it is not actually a language issue. Writing it with a "docs are code" mindset can produce some very clean results. The second biggest issue is that there isn't a good TeX -> HTML compiler.
    • slaymaker1907 2y ago
      You should check out Scribble which uses Racket. It has a bunch of different renderers including HTML and Markdown. However, unlike Markdown, you can easily write extensions for it in Lisp, even within the document itself. https://docs.racket-lang.org/scribble/running.html#%28part._.Extra_and_.Format-.Specific_.Files%29 https://docs.racket-lang.org/scribble/running.html#%28part._... I suppose that makes it inappropriate for something like rendering comments, but it's a great way to write documents. I used it a lot for writing papers since there's a lot less boilerplate and was much easier to use than TeX.
• skybrian 2y ago
  It seems like Markdown works pretty well for writing API docs, where the language has a tool for generating documentation that also gets things like type signatures from the source code itself. The result of running that tool is always API documentation, so you might need something for docs that aren’t structured that way.
• kaizendad 2y ago
  While I definitely understand what the author is saying, the reality is that, for the majority of writing developers will be doing, having something that is easy-to-produce and easy-to-consume is paramount. There are tons of more powerful and flexible options than Markdown, but none that let you create a document that is both computer- and human-readable quite as quickly. Documentation that is written is better than documentation that isn't.
  • bluGill 2y ago
    Which is why I use rST - just as easy to write, but enough more powerful that I'm not left hanging when I realize I need to do something more complex. > Documentation that is written is better than documentation that isn't. I have to disagree with this. I've read too many out of date documents. If documentation exists that isn't correct it is worse than no documentation at all. The only useful documentation is documentation that is correct, easy to navigate, easy to search, and easy to update as the world changes (there might be more?). Good documentation is better than bad, it is debatable if bad documentation is better than no documentation or not (in part because some bad documentation is worse than others).
• Decabytes 2y ago
  Another good documentation choices is Racket’s scribble^1. I like that you can embed Racket code directly into the text, and the language oriented programming of Racket means the syntax is more ergonomic than other systems. There is also pollen^2 but that is more set up for online books by default 1. https://docs.racket-lang.org/scribble/ https://docs.racket-lang.org/scribble/ 2. https://docs.racket-lang.org/pollen/ https://docs.racket-lang.org/pollen/
• nailer 2y ago
  "Now here's how to make an image in rst:" .. image:: example.jpg :alt: alttext Great, I can close this article now.
• taeric 2y ago
  I dislike rST for how cumbersome it is with some of its markers. Trailing underscores, tons of dots, non-fenced sections, nested lists needing extra lines, etc.. It seems actively made to make it hard for me to read the source. Now, granted, I am clearly ok with fenced sections. And I love org-mode for most all things.
• bradboimler 2y ago
  Sure, for quick throwaway notes or messaging apps Markdown is fine. But if I'm gonna sit down and write a proper document? I prefer handcrafting HTML.
• geenat 2y ago
  IMHO, ignoring the parsing difficulty, the main issue with Markdown is it's difficult to write for non-technical users- 1 misplaced character can mess you up if you stick to the "spec". Markdown has already won over the technical users. Enjoy your infinite support tickets caused by markdown. RST does nothing to help this.
• gregopet 2y ago
  I used to hate Markdown (am partial to AsciiDoc myself) but it has "won" and I've just accepted it & use it every day. Not the first time an inferior product did so, and won't be the last. There are a few hills I'd die on, but Markdown alternatives are not one of them.
• fefe23 2y ago
  I don't understand the argument for rST. If you need more control than Markdown can deliver, then write your stuff in HTML to begin with. I have written a ton of documents in plain HTML, including slide decks, documentation for customers, reports for customers, a blog. I have not written a book yet. If I were to write a book, I would use LaTeX because then the typographic fidelity of the output would be my paramount objective. Plain HTML is actually pretty awesome. It allows you to encode the structure of the document and then style if however you wanted. When I started in this business, you had to use LaTeX for that kind of flexibility. HTML has gotten a bad rep, I think, because it's dark side of including Javascript and a ton of frameworks for whatever perceived goal looks easy and seductive and then forces you into serfdom by obstructing future reuse. If you stick with the bare minimum HTML you'll be fine. Better than fine actually. Text processors can these days usually import bare metal HTML just fine if need be. They only fail if you give them the "processed food" output of some kind of rendering pipeline. The only other system for documentation we haven't covered in this thread is troff for man pages :-) Any takers?
  • bluGill 2y ago
    HTML is a bad choice - I want to be able to reorganize my site without have a million dead links. Even if I know what the correct organization is today, requirements will change and so in the future something will be wrong. With rST I can link to a section and move that section to a different document and the links all still work (or if they don't I get an error for each and so I know where to look). With markdown and html I link to a specific document and since each is a document generator there is no warning if I typo the page name (there are a number of tools to look for dead links in html). With markdown I cannot link into a section of the page, only the page itself (some extensions to markdown allow this)
    • paholg 2y ago
      What you see as annoying, I see as a strength. You shouldn't break links; they don't only exist in your site. People will have them bookmarked or shared on the web. There's nothing worse than finding a post online that seems like it will cover your exact issue, but the link is now a 404.
• mmphosis 2y ago
  I prefer What You See Is What You Get (WYSIWYG.)
• beej71 2y ago
  I started looking at converting my books to use Sphinx (from pandoc) and got almost there. What stopped me was something a little odd: I wanted to use different fonts in a link, notably some proportional and some monospace in the same link. And it was my read that this wasn't possible...?
• westurner 2y ago
  A Table of Contents instruction that works across all markdown implementations would be an accomplishment. OTOH, Markdown does not require newlines between list elements; which is more compact but limits the HTML that can be produced from the syntax. MyST Markdown adds Sphinx roles and directives to Markdown. nbsphinx adds docutils (RST) support back to Jupyter Notebooks. (IPython notebook originally supported RST and Markdown.)
• arp242 2y ago
  > When I gush about rST to other programmers, this is the objection I hear the most: it's ugly. To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being? I like my Markdown documents to be nicely readable in source form. Because that's what I'm editing so being readable helps, and it's also what I read most of the time. I don't think Markdown is perfect. I have gripes. But it's "good enough", and damn near everywhere already so it's "in the fingers", so to speak. > Markdown doesn't have a uniform extension syntax or native support for pre-render transforms. Well no, but "Markdown" is also a standard with more implementations you can shake a stick at, whereas most of the alternates mentioned n the article are basically just a program written in $lang, and that's it. I think some do have a spec document, but also don't really have complete alternative implementations, so it doesn't really matter. And I get the point; for my own website I have this ... piece of art ... to transform some of the HTML: https://github.com/arp242/arp242.net/blob/master/_plugins/markdown.rb https://github.com/arp242/arp242.net/blob/master/_plugins/ma... On one hand: eww. On the other hand: it's not strictly needed, hard to do cross-platform, and has been working fine for a long time now. So whatever.
  • philistine 2y ago
    > Well no, but "Markdown" is also a standard with more implementations you can shake a stick at This ubiquity comes in large part from its lineage. Gruber based Markdown on the established cultural standards in raw text emails. The people who quickly adopted it where doing so based on familiarity.
• andrewflnr 2y ago
  > ...Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason. I guess this is why he's not using Pollen, which is explicitly designed for this sort of thing, but based on Racket. I actually settled on rST for writing fiction manuscripts, I think because I actually liked the syntax? Maybe I just needed proper header support. I'm compiling to DOCX via pandoc, so I'm not using the extensibility in the slightest. Anyway, it's amusingly validating to see someone else use it for a similar job.
• unoti 2y ago
  For the motivating use cases, I wonder if YAML and a simple script to transform to other formats as needed would be more effective, easier to read, easier to write, and easier to work with in general.
  • AceJohnny2 2y ago
    No. <Michael Scott "nooo" meme> While a tree datastructure like YAML (or JSON) can be mapped to a document (like HTML, or PDF), as demonstrated by the existence of the DOM tree and the (mis)popularity of XML, the one lesson we should have taken from XML is that it's awkward and you should not mix a tree datastructure with a text markup syntax. Do not make humans have to construct their documentation as a tree first. Let them do in a free-flow way, with markup, and have tools internally convert it to a tree. We've emerged from 20 years of XML-as-a-human-readable-datastructure dark ages. Let's not then make the opposite mistake.
  • remram 2y ago
    What's the YAML syntax for "That's a _weird_ idea, [YAML](https://yaml.org/ https://yaml.org/) is a data serialization language"?
• hintymad 2y ago
  > .. image:: defines the image "directive". When Sphinx reads it, it looks up the registered handler for the directive And the author continues to explain how rST is convenient and flexible to a doc engine like Sphinx. This kind of argument confuses me as a user. That is, why would I care? I just want to write my doc fast with minimal effort, and couldn't give zero attention to how Sphinx works. Wouldn't an average user like me should just ask: what will rST offer that is 10X better than Markdown?
• crowcroft 2y ago
  Markdown might not be the best at anything, but it's pretty good for a lot of use cases and is beautifully simple. I can teach a non-technical friend markdown in about five minutes.
• asmeurer 2y ago
  The author claims that RST is nice because it's extensible, but as someone who's written some Sphinx extensions, I can tell you that extending RST is not as pleasant of a task as the author makes it out to be. I don't really know what it's like in Markdown world, but the underlying tools (Sphinx and docutils) are very difficult to work with, and make many implicit assumptions that make certain things difficult or impossible.
  • romanovcode 2y ago
    I think author should write HTML if they want extensibility so much. Not like RST is reading-friendly to begin with.
    • ideasman42 2y ago
      Keep in mind you might not _only_ be exporting HTML.
  • ideasman42 2y ago
    I've written a few Sphinx extensions ... it seemed OK to me, a bit awkward but long term - this is the kind of thing you do rarely & use often, so how nice it is to write extensions is barely an issue.
• innocentoldguy 2y ago
  I don't mean to hijack a conversation about ReStructuredText, but if you're looking for a markup language that gives you more than Markdown, look at AsciiDoc rather than ReStructuredText. I have written technical documentation using all three for years and AsciiDoc is superior to both ReStructuredText and Markdown, in my opinion. For example, Markdown's and ReStructuredText's support for tables is cumbersome to say the least. AsciiDoc's table formatting is much easier to read, write, and maintain, and AsciiDoc tables are more robust, supporting headers, captions, custom dimensions for tables/rows, and complex formatting within tables. Some other benefits include: • A single, standardized format where Markdown and ReStructuredText do not (in other words, there are no "flavors" like you have in Markdown). • Concise and readable syntax. • A more gradual learning curve that ReStructuredText (probably due to its consistency and excellent documentation). • Superior styling options for your output. • A superior toolchain to the other two markup languages. • A rich set of built-in documentation features, so you rarely have to rely on third-party plugins. AsciiDoc was designed from the ground up for technical documentation, whereas the other two get shoehorned into that role. Having worked extensively with all three, I can't recommend AsciiDoc highly enough.
• concombres 2y ago
  I love rst. I love sphinx. I've written a lot of things with it. But, I use markdown. Markdown is technically inferior, but it's just simpler and that's really what makes all the difference. There's things I can do in rst that are more logical, more powerful - and yet - I still use markdown and pictures. To me, it's the usual problem that I like to illustrate with a config file: while True: 1. You need a config. You make a text file and write values in it. It grows. Its unmanageable. It's terrible. 2. You write some proto to store the config. Its complex. It can do everything. It's relatively good but the more you use it, the more little problems show up. It looks like regedit, a sql database, a tree of trees, etc. 3. You throw it all away and write something with trade offs, that is reasonably simple, solve 80-90% of use cases and is otherwise somewhat limited. Sometimes, it feels like you might as well just use a text file.
  • ideasman42 2y ago
    Strange that everyone seems to think it's simpler, it seems might be a web-developer bias here. I'm not a web developer and I don't find markdown especially easy/pretty/simple... I find it annoying when the same markdown can't be used in different places based on the rendering engine and there aren't standard ways to extend it. Also, having trailing whitespace as part of the spec.. tsk!
• ktosobcy 2y ago
  If it's a matter of preference then whatever. We had our documentation in asciidoc and it was awesome to write. We migrated to RTD/Sphinx/rST mainly for 1) better handling of i18n and 2) better handling of multiple-version-documentation (switching between versions)... and I loath rST every day. It's syntax is just abysmally awful and the tooling sucks (seriously, it's not just bad... it sucks!). Nowadays there is antora but still - i18n is still a problem… And markdown - as a simple tool to add some simple and basic formatting is just awesome and it's easily readable even if you don't have parser and end up having to read plaintext…
• wiresurfer 2y ago
  I have grappled with the same conundrum. Here are my takes on documentation writing. First is the X axis of type of document we are called on to write. 1. There is personal writing. books included. 2. Personal Blogging and Dev Rel publishing. 3. Then there is developer tool documentation. [code snippets, sdks, libraries] 4. Then there is product documentation. [images, steps, how tos] Then there is Y axis of tools. 1. markdown and with it Z axis of mkdocs, hugo, KMSs like obsidian <name everything markdown here> 2. rst 3. org? 3. wysiswg editors or anything custom. I find - markdown both ubiquitous and somewhat approachable. for most beginners. with obsidian/logseq/... it can also work for non tech writers too. its also more widely supported. [Github i am looking at you] - dev rel/dev tools docs with sphinx and rst is absolutely godsend! also a vibrant ecosystem. - product docs with mkdocs x markdown if its a consumer facing docs with lots of images and need for customizing. rst if its a developer product. --- I write my blog in markdown, https://blog.shaishav.kr https://blog.shaishav.kr My team maintained https://userdocs.rapyuta.io https://userdocs.rapyuta.io in markdown for the last 4 years. https://github.com/rapyuta-robotics/rapyuta-io-docs https://github.com/rapyuta-robotics/rapyuta-io-docs - we also maintained https://sdk.rapyuta.io/ https://sdk.rapyuta.io/ & https://cli.rapyuta.io/ https://cli.rapyuta.io/ both in semiautomated rst + github actions setup
• zelphirkalt 2y ago
  rST is also much more powerful than Markdown. You can write an academic papar properly in rST. You can add custom directives implemented in Python and stuff. If I could make everyone use rST instead of Markdown, I would. Of course Markdown is simpler in many aspects. But therefore it lacks many things that rST has.
• necovek 2y ago
  It's funny how people are commenting as if reST was created as a competitor to MarkDown: it's actually quite the opposite. reST was a 2002 evolution on StructuredText from even earlier, and MD was first publicized in 2004. They've got extremely similar goals, and for the most basic text, both read and write like plain text too. And it was obviously a time when this thing simply became a thing everybody desired, so many "formats" appeared. Why did MD win has — IMO — nothing to do with how it's "simpler" or "more readable" — they are largely interchangeable for anything that's easily represented with whitespaces in pure ASCII. Or does someone claim that the following is unreadable gibberish that they need a parser for? The best friends ================ ``markdown`` and ``reST`` are two formats that *largely* aim to achieve the same goals: * Be simple to read without any parser * Be quick and simple to type out I really, really don't see how the Markdown variant of the above is better in any way (note that I am not saying that reST is better either)? It's mostly the weirdness of history that has one prevail over the other, but both are good enough for their core goals.
  • radlad 2y ago
    You've provided a very simple example that can be performed easily in both Markdown and reST. reST offers a lot of additional formatting features which are beneficial if you need them and cruft when you don't. I first started using Github-flavored Markdown after signing up for Github in 2010 (possibly earlier under another alias.) I used reStructuredText for Python docs a couple times. I found the latter to have a much higher learning curve and I haven't had a reason to use it since.
    • necovek 2y ago
      In general, either will be simple as long as your input is simple, and they will become complex as soon as you want something complex — I am pretty sure people here bringing the pitchforks are really not even aware of how reST looks like in the first place. But looking through examples at https://docutils.sourceforge.io/docs/user/rst/quickref.html#inline-markup https://docutils.sourceforge.io/docs/user/rst/quickref.html#..., I really see a lot of non-simple stuff done in an obvious way too (block quotes, tables, bullet and enumerated lists, sections and headings, separator lines...). By the time you got on the markdown train, it has already won out, and you've probably seen a lot more of it than of reST, even if MD still wasn't standardized. As a counter-point, having done lots of reST with Python docutils prior to 2010, I still mix up reST and MD — there's nothing intuitive about any of their special syntax, and our perception is mostly tainted with our prior experience. I've also written a lot of ASCII-only docs prior to either of those, and most people used ever-so-slightly different conventions there as well (somebody mentioned using /this/ for italics as well). reST was standardized in the form of a Python PEP from its inception so you could at least rely on learning it once. Edit: My ultimate point is that you (and most everybody else, including me) are using MD because it's more popular, not because it's "better".
• fireflash38 2y ago
  I used rST and Sphinx along with a custom built test reporter to generate a huge amount of test documentation for compliance. It really was nice to work with, especially since it is the default for python docstrings too.
  • aidenstern 2y ago
    What kind of compliance? I’m working through the same thing right now and trying to decide between sphinx and mkdocs
    • fireflash38 2y ago
      Common Criteria. Stuff that needs insane amounts of documentation of your testing.
• fridder 2y ago
  Perhaps it is just how it was implemented the last time I used it but rST+Sphinx was so finicky and annoying that engineers just stopped updating the docs.
• oglop 2y ago
  Ok well, that was insane. I absolutely despise working with restructured text. Markdown I use allllll day long and it’s simple, fast, and a pleasure comparatively. People like this just want to make the rest of us miserable.
• dheera 2y ago
  I prefer just vanilla HTML. It's easy to read and you can tack a stylesheet at the top to make it look actually nice and directly renderable in a browser without needing any parser.
• __mharrison__ 2y ago
  I wrote my books for years with rST. (I also used Asciidoc, and one publisher wanted me to use Word.) Recently, I migrated all of my tooling to Markdown. It turned out that no single markup language supported all of the features required to make physical books, so I would need custom tooling regardless. The rest of the world was moving onto MD, and even though I'm a huge Python fan, rST is painful, and writing tooling with it is even worse. (I also have commit rights for docutils.) I don't regret my choice one bit. It has made my life much easier, and I can work much faster today.
• AndIHateLatex 2y ago
  I never gave rST an in-depth look. This article made me. I am utterly disappointed. I want markdown for writing loose text in a way that will be shared with and edited by non-technical people. If something is not formatted such that it can be placed in-line, then we're entering the real of "function" abstractions, which non-technical people DESPISE WITH A PASSION. They won't say it, but I'm old, and wise enough to know it's a mistake. In other words, Markdown is just an expanded BB Code for me. And it does its job very well, because BB Code was insufficient. So that's the context in which I'm disappointed with rST here. Because it look like... A poor man's LaTeX. This stuff is way too complicated for Markdown's use case, and way less complex than the demands of a book. I don't want to take the use case of LaTeX and use a worse tool. Disappointment. That's all.
• rk06 2y ago
  rST is very powerful but if you have rST-illterate people on your team and you would like them to contribute, tough luck. Passion for most powerful tech can take you far, but not tohers in your team. For others, Markdown has a much lower barrier to entry and is easier to preview in your local editor
• daghamm 2y ago
  Can't we all agree that both suck and everyone should use org? Jokes aside, org seems to have a more clear specification and is very easy so use. Why don't more people use it? I think Github already renders README.org as good as README.md and READEM.rst.
  • ideasman42 2y ago
    ORG's tightly integrated into emacs & it's ecosystem. It's fine but I don't think there is an equivalent to Sphinx for large cross referenced documents, with different outputs formats & support for translations (different languages). Perhaps some of these things exist - I may be wrong, if they do I doubt the system is as mature or well supported as Sphinx's.
• _xiaz 2y ago
  So it's more complex than markdown while being less powerfull than latex or org-mode? What a waste
• fermigier 2y ago
  Typst has a cool syntax and is highly extensible. I wish there was a way to use it to render HTML and not just PDF.
• mrled 2y ago
  I am kind of syntax agnostic and would be happy to use more complicated syntax in exchange for more power. (I have a lot of HTML inside my Markdown files, too.) However, my use of rST has been in Sphinx, and I want to love it because it's quite powerful, but it's so slow. Am I missing some configuration or third party package to fix this? I wrote about 15k words of English text in rST in Sphinx to document a project[^1], and Sphinx's build speed was many times more an impediment than my unfamiliarity with rST. [1]: https://pages.micahrl.com/progfiguration/ https://pages.micahrl.com/progfiguration/
• gigatexal 2y ago
  I’m not convinced. Markdown is cleaner imo and basically the standard. I see no reason to move.
• red_admiral 2y ago
  The way of the world is this: ISO comes up with SGML, everyone gets a pat on the back, and then some guy called Tim who isn't even on a standards committee comes up with some bastardised version where you have to use angle brackets rather than generic customisable delimiter classes, and there's things like `<b>` for bold that are not even semantic. Guess which one took over the world? I write a lot of markdown at work, and while you can't do this in commonmark, most parsers will absolutely let you define custom block types and transform the doctree and other things. You know how three backticks followed by the word 'python' produces syntax-highlighted code almost everywhere? You bet that I can do `::: warning` in my documentation to make the following content appear in a big red box with an exclamation mark. As long as you don't put raw HTML in your source, you can even render to different targets like PDF. jupyter-book is a good example here.
• 0xbadcafebee 2y ago
  My grandmother can create better docs than most programmers, but not because she's some technical wizard. She uses MS Word. Imagine, a program designed to allow humans to lay out and format a document quickly and easily... programmers prefer to hack up ascii art and forego the graphical layout and formatting tools developed 30 years ago. And then they complain that docs are hard to read/write...
  • kstrauser 2y ago
    Grandma’s doc may not be readable in 30 years. I can look at basically every text file written since ASCII came along with standard tools. Also, since Grandma isn’t a programmer, she’s probably not collaborating on her doc with a bunch of distant people using a version control system with patch requests. Shiny tools are nice when it’s only you and you don’t need to keep the results forever.
    • 0xbadcafebee 2y ago
      Lol, dude, Word files have been readable by open source tools since forever. MS Word itself supports many different formats including OpenDocument, so there is absolutely no problem with being able to read them in 30 years. MS Word supports version control, but patches are a terrible idea for documents. Again, the whole point of a document is to make it easy to read, so the formatting becomes a huge pain in the ass for a patch. Patches are designed for lines of code, not the formatting, layout and content of rich text documents. Trying to force documentation to work like code is making the computer happy, rather than the computer making people happy. It's the opposite of what technology is supposed to be for. Think about what you're spending your life on. You gonna look back when you're 80 and think, gosh, I'm so glad I spent those extra hours going back and forth with a dozen people on the internet to try to approve an update to documentation? I'm so glad I spent an extra hour tweaking this program code so that this document would have an embedded table aligned right? I'm so glad I had to write a separate program to be able to format this Markdown Table so that I could actually edit and save it so that it renders? Docs should be living / not require requests for patching. Humans should be entrusted to just update a document immediately, with a log and comments to allow reverting entries only if necessary. Aka a wiki (and a WYSIWYG one at that). The whole purpose of patch requests is not to gatekeep information, it's to make sure a change doesn't blow up a program. Documentation isn't a program, just change the document.
• HenriTEL 2y ago
  To me the main deal breaker with reST is titles that must be underlined with punctuation characters at least as long as the title. That's very annoying to write, and some people even add overlining. We're entering the ascii art domain here and I don't have time for that.
• wiseowise 2y ago
  > I can't get into lisps for the same reason. I assume they’re talking about s-expressions? Then that’s a really bad example, because those are objectively beautiful.
  • psychoslave 2y ago
    What are the objective criteria in that case?