[HN Gopher] I prefer rST to Markdown
___________________________________________________________________
I prefer rST to Markdown
Author : BerislavLopac
Score : 237 points
Date : 2024-07-31 15:49 UTC (7 hours ago)
(HTM) web link (buttondown.email)
(TXT) w3m dump (buttondown.email)
| PaulHoule wrote:
| 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 wrote:
| 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
|
| The entire point docutils is to parse formats and convert using
| an API: https://www.docutils.org/docs/index.html#api-reference-
| mater...
| PaulHoule wrote:
| 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 wrote:
| Ah, you want something like pandoc, but you can manipulate
| the internals as needed?
| PaulHoule wrote:
| Yes, and with a somewhat different focus. I wish I could
| throw in 1000 pages of reference documentation, align it
| semantically with a few pages of documentation about a
| particular topic and then enrich those pages with
| snippets pulled out of the reference material. And things
| like that.
| hgs3 wrote:
| > something HTML-based
|
| Instead of HTML you can use XML to write structured documents.
| With XML you can define whatever custom tags you need with
| schema validation if desired. The advantage of this approach is
| you have full control over the input schema and output, but the
| downside is XML is much more syntactically noisy compared to
| Markdown or RST and you will need a script to parse & convert
| the XML to your preferred output format(s).
| giantrobot wrote:
| > Markdown or RST and you will need a script to parse &
| convert the XML to your preferred output format(s).
|
| XSLT will happily output any number of formats from an XML
| doc. There's also a number of existing and very capable XML
| schemas for documentation like DocBook. You can even go from
| a lightweight markup like RST or Markdown to DocBook and then
| have an XSLT pipeline that delivers that intermediary to any
| number of formats. There's also very capable graphical
| editors that will spit out DocBook directly.
|
| I find the aversion to XML very strange. It was definitely
| applied in some places poorly by products with "Enterprise"
| somewhere in the name but the language itself is very useful.
| The aversion to XML has led to a lot of work re-learning of
| the lessons that led to some XML features. It's also led to
| implementing XML features poorly in other languages.
| SoftTalker wrote:
| Yeah I always liked XML as a data format and combined with
| XSLT it is quite powerful.
| PaulHoule wrote:
| What I really like with XSLT is what you can do with
| user-defined functions. Not only are they helpful in
| implementing transforms but you can also write stateful
| functions that insert rows into a database or something.
| wpm wrote:
| You're not alone. I find XML to be massively more readable
| and flexible. I work in the macOS/iOS IT space, and our
| bread and butter is the Property List, which tends to
| either actually be XML underneath or is at the very least
| rendered like XML, all just conforming to the plist DTD
| (which is pretty short). These plists that conform to this
| fairly simple DTD are enough to describe every init task
| and background process to the OS, every preference in
| applications that use UserDefaults and CFPrefs (which is
| most), and I use them for storing structured data in and
| out of scripts that I throw together.
|
| Loads of other systems I work with still output XML, and I
| have fast, powerful tools to work with them pre-installed
| on any Mac I work on, and it doesn't even matter that Apple
| hasn't updated them in a while since XML hasn't really been
| changed either. I can look at an XML doc and have so much
| information about the data inside just telegraphed into my
| head, just by the way the things are shaped. I don't have
| to _read_ the tags like a book, I can just gloss over them
| and still get enough to understand the strings /numbers
| inside. Yet, they're still on the page, out of focus, in my
| periphery, providing anchoring and structure and
| navigation, I can find my place. Maybe I'm just a freak, or
| that comes from 20 years of staring at them. Whatever
| reason, I just can't do that with JSON as easily or as
| fast.
|
| I don't hate on any of the other formats (save for YAML,
| not interested), and I really appreciate JSON's brevity
| sometimes for simple data and small responses, but that
| brevity quickly turns into wisps of formatting and text
| seemingly floating out in the middle of nowhere.
| giantrobot wrote:
| > I don't hate on any of the other formats (save for
| YAML, not interested), and I really appreciate JSON's
| brevity sometimes for simple data and small responses,
| but that brevity quickly turns into wisps of formatting
| and text seemingly floating out in the middle of nowhere.
|
| Same. Every back end project I work on I recommend XML as
| the transport and every time I get a reflexive "ugh,
| XML". Then I spend an inordinate amount of time making
| Swagger endpoints so a consumer can figure out how the
| JSON output is supposed to behave.
| _heimdall wrote:
| Once you get that far, XSLT is waiting for you if you need to
| render XML to HTML.
| andrewflnr wrote:
| Yes, waiting in the dark, with teeth.
|
| (I kid, mostly. It was a mild pain in the projects I used
| it for, and I've heard much worse horror stories than
| mine.)
| _heimdall wrote:
| Same. I've used it for small projects, like styling an
| RSS feed. I imagine it gets tricky fast in anything
| larger.
| tannhaeuser wrote:
| Pro-tip: use SGML which has it all:
|
| - is a superset of XML (XML is derived from SGML as a
| simplified, proper subset)
|
| - can parse HTML precisely with all bells and whistles such
| as tag omission, enumerated attributes and other shortforms
| (which are based on SGML after all)
|
| - can define markdown syntax as an SGML SHORTREF
| customization (note that SGML can not cover _all_ of markdown
| syntax; for example, defining reference links somewhere at
| the end of a document and expecting SGML to pull a href URL
| into the place where the link is referenced won 't work with
| SGML SHORTREF)
|
| The combination of markdown-as-sgml and inline HTML or HTML
| blocks is particularly nice and predictable, and also informs
| further customization such as using entities (text
| variables), custom elements, and other advanced SGML stuff
| with markdown that comes up frequently as a requirement.
| euroderf wrote:
| rST and Asciidoc seem roughly equivalent in terms of
| capabilities. Are they roughly equivalent in terms of
| weaknesses and missing features, I wonder.
| bobbylarrybobby wrote:
| I think they're about equal, although asciidoctor has bold
| italics, which rST does not.
| complex_pi wrote:
| I can't test (no computer right now) but can't include
| directives achieve what you want?
| benji-york wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| bluGill wrote:
| Every language has its down markdown - but they are not
| compatible with each other unless you stick to the very basic
| which doesn't do much. Which is why every implementation has
| extensions - it isn't hard to add extensions and there are a
| lot of obviously missing things from the basic.
| Macha wrote:
| Yet at the same time I'm able to write Markdown that parses
| and renders correctly in VS Code, Obsidian, and the Rust-
| based static site generator I use. Sure, Obsidian has
| incompatible features I could use like [[Wiki Links]] but I
| don't have to.
| bluGill wrote:
| That is easy enough as long as you are only writing a
| simple one page readme type document. To be fair that is
| the majority of what people write. However if you write
| anything more complex you will run into issues.
| jcranmer wrote:
| Is there any rich text format which is well-supported
| across multiple languages? The closest I can think of is
| HTML, but even that has its fair number of issues...
| osmarks wrote:
| CommonMark mostly fixes this.
| xigoi wrote:
| At the expense of being extremely complex.
| marcosdumay wrote:
| People don't add it because it is ugly and verbose.
|
| And then people don't create any new format for its use case
| because it already exists.
|
| Almost everything good we have only exists because some person
| irrationally decided to do it, against all common sense and
| logic.
| jawns wrote:
| > 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 wrote:
| 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 wrote:
| 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.
| ryan-c wrote:
| Convenience? I have a "spoiler" role for rST, for example,
| which works like this: # state class to
| contain the counter class _spoiler: count
| = defaultdict(lambda: 0) def id(src):
| _spoiler.count[src] += 1 src_hash =
| sha256(src.encode()).hexdigest()[:7] return
| f'spoil-{src_hash}{_spoiler.count[src]:03}'
| def spoiler_role(name, rawtext, text, lineno, inliner,
| options={}, content=[]): src =
| inliner.document.attributes['source'] html = (
| '<input id="{id}" type="checkbox" class="spoiler" checked
| />'+\ '<label for="{id}"
| class="spoiler">{text}</label>'
| ).format(text=text, id=_spoiler.id(src)) return
| [nodes.raw('', html, format='html')], []
|
| I don't want to do that manually, and this lets me write
| :spoiler:`Rosebud was the name of his sled`.
| eddd-ddde wrote:
| That's like saying why use C++ templates if you can just
| write the same function for every type that needs it. Now you
| don't need template instantiation!
|
| The point is that it's objectively better when you want to
| separate the concerns of writing content and rendering it. It
| makes writing much easier and keeping the layout consistent
| as well.
| osmarks wrote:
| Preserving the semantic content is helpful if you think you
| might want to switch the rendering later.
| teamspirit wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| > 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/
| simonw wrote:
| 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 wrote:
| 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 wrote:
| The article convinced me that markdown is better for its
| purpose.
| Spivak wrote:
| 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.
| woodrowbarlow wrote:
| all of that is true, but markdown targets HTML as its
| "native backend", if you will. it is not feasible to render
| markdown -> pdf without having an intermediate HTML
| representation.
|
| this is clear from the fact that HTML can be inlined in a
| markdown document; this is part of the spec (in so much as
| there even is a "spec" for markdown, anyway).
| latexr wrote:
| > to the point that Markdown parsers support dropping actual
| HTML tags mixed in the the markup.
|
| _Some_ Markdown parsers support _some_ HTML. You cannot, for
| example, add a YouTube video embed to a GitHub comment.
| Webpages that allow Markdown quite reasonably limit what's
| accepted.
| samatman wrote:
| Usually, the colloquial conflation of Markdown with
| CommonMark and the numerous Markdown-esque dialects is
| helpful language, I've defended it here before.
|
| On this question, it isn't.
|
| Markdown _qua_ Markdown, unambiguously supports HTML tags.
| You can verify that yourself:
| https://daringfireball.net/projects/markdown/
|
| The introduction being:
|
| > _Markdown is a text-to-HTML conversion tool for web
| writers. Markdown allows you to write using an easy-to-
| read, easy-to-write plain text format, then convert it to
| structurally valid XHTML (or HTML)._
|
| It's not possible to read the original specification
| without agreeing that, yes, Markdown is specifically a way
| to generate HTML. It also has a nice syntax which has
| become popular in contexts where embedding HTML isn't a
| good idea, and there are some tools which allow Markdown to
| be converted to other formats as well (usually, but not
| always, these disallow most HTML tags, meaning that they
| aren't Markdown _sensu stricto_ either).
|
| I would say that all of this supports Hillel's basic point
| here: Markdown is in fact tied to HTML semantics, in a way
| which makes it painful to do things with it which aren't
| tied to those semantics in the same way. Dialects in the
| Markdown family exist which make this less painful, and
| they do so by diverging from the original Markdown spec.
| latexr wrote:
| > Markdown _qua_ Markdown, unambiguously supports HTML
| tags.
|
| The section I quoted (and responded to) didn't say
| "Markdown supports HTML tags", it said (emphasis added)
| "Markdown _parsers_ support (...)".
|
| So unless you're arguing that a tool cannot be considered
| a true Markdown parser1 unless it parses HTML, the
| distinction is irrelevant. I wasn't making a general
| argument, I was responding to a specific claim.
|
| > You can verify that yourself
|
| Yes, I am quite familiar with that subpar piece of code
| and specification. I have spent some time implementing a
| Markdown parser myself (the output wasn't HTML) and
| Gruber's resources were _by far_ the worst. For various
| reasons he has been an awful steward of Markdown; its
| ubiquity is _despite_ him, not because of. Forgive me if
| I don't find the author to be _the_ authoritative source
| anymore.
|
| 1 https://en.wikipedia.org/wiki/No_true_Scotsman
| travisjungroth wrote:
| I think you've kinda lost the thread. From the top
| comment:
|
| > Markdown was designed...
|
| Surely Gruber is an authority on that.
|
| And anyway, " markdown is a lightweight representation of
| html" is _true enough_ that calling it "decidedly
| incorrect" is wrong. Certainly it's not a point that's
| supported by going to author intent.
| latexr wrote:
| > And anyway, " markdown is a lightweight representation
| of html" is true enough that calling it "decidedly
| incorrect" is wrong.
|
| Yes, I completely agree with that.
|
| And that wasn't the point I quoted or responded to.
|
| > From the top comment
|
| Again, I wasn't replying to the top comment, I was
| replying to _what I quoted, from the comment I replied
| to_.
| The_Colonel wrote:
| Gruber:
|
| > Markdown's syntax is intended for one purpose: to be used
| as a format for writing for the web.
|
| Both Gruber's original and CommonMark (the closest thing to
| a standard) support inline HTML.
|
| Both Gruber and CommonMark specs are defined in terms of
| its HTML output.
| latexr wrote:
| Yes, that's why I said "some". I don't understand what's
| ambiguous about that.
| velcrovan wrote:
| The very first sentence in that link says "Markdown is a text-
| to-HTML conversion tool for web writers."
|
| Gruber did not take a "de facto standard" from Usenet and
| simply write an HTML converter for it. He designed his own
| markup, borrowing from Usenet and other conventions. The
| "Acknowledgements" section at the bottom of your link alludes
| to this fact.
|
| Markdown was from the beginning intended as a markup syntax for
| web CMSs. To say it is a lightweight representation of HTML is
| correct. The whole point was that every part of the syntax
| produce a direct HTML equivalent.
| CharlesW wrote:
| Gruber writes that Markdown is two things: (1) a plain text
| formatting syntax; and (2) a software tool, written in Perl,
| that converts the plain text formatting to HTML.
|
| > _To say it is a lightweight representation of HTML is
| correct._
|
| It's correct in the context of (2) but not (1). In the
| context of (1), Markdown is a lightweight markup language for
| rich text. For example, Pandoc can convert Markdown to
| formats like PDF, LaTeX, and ePub.
| The_Colonel wrote:
| Isn't inline HTML valid within Markdown? You could say that
| Markdown is a superset of HTML.
| CharlesW wrote:
| That's an excellent point. Time to update
| https://www.wikiwand.com/en/Markdown. :^)
| rpdillon wrote:
| It's also true in the context of (1), since the syntax
| specification specifically falls back to HTML for difficult
| things like tables.
|
| This is made abundantly clear on the Syntax page[0]:
|
| > Markdown's syntax is intended for one purpose: to be used
| as a format for writing for the web.
|
| > Markdown is not a replacement for HTML, or even close to
| it. Its syntax is very small, corresponding only to a very
| small subset of HTML tags. The idea is not to create a
| syntax that makes it easier to insert HTML tags. In my
| opinion, HTML tags are already easy to insert. The idea for
| Markdown is to make it easy to read, write, and edit prose.
| HTML is a publishing format; Markdown is a writing format.
| Thus, Markdown's formatting syntax only addresses issues
| that can be conveyed in plain text.
|
| > For any markup that is not covered by Markdown's syntax,
| you simply use HTML itself. There's no need to preface it
| or delimit it to indicate that you're switching from
| Markdown to HTML; you just use the tags.
|
| Markdown is very coupled to HTML, and is hobbled as a
| result compared to formats like Tiddlywiki and Org that not
| only have sophisticated syntax for all kinds of content
| like tables, but also directives to the parser itself to
| render particular blocks using an external tool. I wrote a
| bit about this in 2021 in response to query about why Org
| mode doesn't use Markdown[1].
|
| [0]: https://daringfireball.net/projects/markdown/syntax
|
| [1]: https://rpdillon.net/why-doesnt-emacs-org-mode-just-
| use-mark...
| chrismorgan wrote:
| Markdown, _Markdown_ , is nothing to do with email and Usenet
| formatting. It was a specific syntax, poorly defined, which has
| since become a broad family of mostly similar syntaxes; and it
| was _inspired by_ various conventions from things like email
| and Usenet, some of which predate _computers_ (e.g. pretty sure
| I've seen or heard of asterisks being used for italics in old
| typewritten stuff); but Markdown is all about HTML, its syntax
| is _extremely_ constrained by HTML, and any attempts to
| separate it from HTML are fairly thoroughly doomed.
| masklinn wrote:
| Saying that it has _nothing to do_ with email /usenet is a
| bridge too far in the other direction, it was very much
| inspired by such formatting, something it never hid:
| https://daringfireball.net/projects/markdown/
|
| > the single biggest source of inspiration for Markdown's
| syntax is the format of plain text email
| chrismorgan wrote:
| Yeah, it was _inspired_ by those things, as I said, but it
| was never connected to them, and is quite incompatible with
| them.
|
| I also express things that strongly because I've observed a
| distinct tendency to interpret Markdown as the successor of
| those things or the inventor of such syntax ideas. Whereas
| in fact, Markdown was not the first lightweight markup
| language, and is not the only one, and isn't even the LML
| unquestionably closest to plaintext email conventions
| (reStructuredText is an obvious contender; overall, I'd
| consider reStructuredText a little closer than Markdown,
| but it's subjective).
|
| Perhaps my intent would be more clearly expressed by
| inverting it: _email formatting_ has nothing to do with
| _Markdown_.
| masklinn wrote:
| > Yeah, it was inspired by those things, as I said, but
| it was never connected to them
|
| You seem to have a very peculiar interpretation of the
| word "connection"
|
| > and is quite incompatible with them.
|
| It can't be incompatible with ad-hoc unspecified and
| informal formatting habits.
|
| > Perhaps my intent would be more clearly expressed by
| inverting it: email formatting has nothing to do with
| Markdown.
|
| That's just as inane for the same reasons.
| keybored wrote:
| You're both right. The original implementation was a superset
| of HTML. Do the lightweight syntax for the common stuff and
| HTML for the rest.
| js2 wrote:
| Dear HN: stop leaving comments like this. It's arguing over
| semantics and makes for boring conversation. It also violates
| HN guidelines for leaving comments:
|
| - Please respond to the strongest plausible interpretation of
| what someone says, not a weaker one that's easier to criticize.
| Assume good faith.
|
| - Please don't pick the most provocative thing in an article or
| post to complain about in the thread. Find something
| interesting to respond to instead.
|
| https://news.ycombinator.com/newsguidelines.html
|
| If you disagree with the substance of the article, say you
| prefer Markdown to rST, then address that. Explain why despite
| the author's preference for rST, you prefer MD. It's silly to
| argue over this single sentence about exactly what Markdown is
| or isn't.
| tombert wrote:
| Yeah, that's what I feel gives markdown an edge over nearly
| anything else; markdown is adopting conventions that were meant
| to be readable without any kind of rendering. I can very easily
| tell what my markdown document is going to look like before I
| render it with Pandoc, because it's basically just taking stuff
| people were using with plain text that was meant to be read
| directly anyway.
|
| I haven't used rST, but looking at the examples it looks
| considerably less readable out of the box.
| Spivak wrote:
| Oh it's not that bad. * one * two
| * buckle my shoe | inspiring quote | -
| some famous guy foo a kind of bar
| bar part of a foo :red: stop
| :yellow: speed up :green: go - code::
| python def fun(): pass
| Go here_ for more info. - :: here: https://google.com
| My **strong** text is well *emphasized*. Very ``literally``.
| simonw wrote:
| 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/
|
| 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 wrote:
| 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#...
|
| that is one of the things I miss most about writing in rST, for
| sure.
| jasonpeacock wrote:
| 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
| louwrentius wrote:
| The one-line summary is:
|
| > I think Restructured Text is better for writing books than
| Markdown.
|
| That would be a better title.
| Karellen wrote:
| 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 wrote:
| 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/
|
| Designed by one of the authors of CommonMark, an attempt to
| specify a standardized flavor of Markdown.
| 0cf8612b2e1e wrote:
| 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 wrote:
| 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#discussioncommen.
| ..
| the__alchemist wrote:
| Indeed; Github will now render TeX in markdown documents, eg
| when displayed as a repo's readme. Very convenient.
| breck wrote:
| 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/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/ -- might
| do everything you need in a simpler way!
| bluGill wrote:
| 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 wrote:
| One solution:
|
| https://pandoc.org/
|
| Or "how I stopped caring about doc formats"
| morbicer wrote:
| 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 wrote:
| > 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 wrote:
| >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
|
| >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 wrote:
| Personally, besides it being a nice format, I use Markdown to
| honor Aaron Swartz.
| Ericson2314 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| (Even with pandoc, 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 wrote:
| OK that specific example works, but what about his later
| problem vs solution one? One runs out of hacks pretty quickly.
| romanovcode wrote:
| 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 wrote:
| 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.
| tristor wrote:
| 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 wrote:
| 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 wrote:
| 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. 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
|
| 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.
| ak217 wrote:
| Agreed that Sphinx is extraordinary and wildly underrated.
| Sphinx is the only _architecturally sound_ , extensible, widely
| used documentation framework that I know of. Its plugin
| ecosystem is amazing and gives me incredible leverage to
| improve documentation for teams and projects.
|
| I'm not a fan of reStructuredText, but nowadays it's possible
| to do most things that previously tightly coupled Sphinx to RST
| in Markdown, courtesy of MyST-Parser:
| https://github.com/executablebooks/MyST-Parser
| bluGill wrote:
| Except that the plugins are not compatible with each other or
| the latest version. That means I'm seeing some bugs that are
| fixed in the latest but I can't get the fix because my
| doxygen plugin doesn't work with the latest, and even if it
| did is the mermaid plugin updated yet? (please don't ask
| which versions of each I'm using - I believe there are at
| least 2 different ones that can do both of the above and they
| all have different abilities...)
| skybrian wrote:
| Some drive-by feedback on pigweed.dev: It seems like it's
| missing a "What is Pigweed" section? I was wondering what
| Pigweed does and eventually found the Github README, which is
| somewhat better. (I've used Arduino, but I'm not quite sure
| what I'm looking at.)
| shepherdjerred wrote:
| Why do you like Sphinx so much? Have you ever used
| MkDocs/Material for MkDocs? How do they compare?
|
| At my last job I spent a fair amount of time on documentation,
| but I don't have a great understanding of what technical
| writers like/dislike, or what documentation systems are best.
| bluGill wrote:
| I like sphinx because I can make it do all the weird links
| between documents that I want. Markdown can't do that. I've
| never used MkDocs so I cannot comment.
| einpoklum wrote:
| > reStructuredText (reST) by itself can be pretty rough. reST
| combined with Sphinx is pretty great.
|
| So, you've made a convincing argument of why we should prefer
| Markdown to reST, 9 times out of 10. If we're working with
| Sphinx we'll give it serious consideration.
| Spivak wrote:
| I'm not really sure what your point is. What you're saying
| agrees with both the parent and the OP.
| einpoklum wrote:
| My point is that the reason GP prefers rST is a reason not
| to prefer it, usually.
| eska wrote:
| _Yes, what this means in practice is that it 's easy to
| customize common aspects of your site (such as how images are
| displayed)._
|
| I found this to be very easy using Markdown+pandoc. I turned
| image tags containing youtube links to thumbnails with video
| tag and alt text, hooked up image tags to local video files to
| ffmpeg to optimize and resize videos to then do the same, etc
| in a few lines of code.
| pbowyer wrote:
| > 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
|
| This, so much this.
|
| It's a problem in an even more general form (for you're writing
| about linking to sections within a page): the number of CMS
| systems or static site builders that make you insert the final
| URL when you write is _insane_.
|
| If the slug changes, you reorganise your site - now you have to
| do a search and replace through the site to update all your
| links.
|
| Static site generators could enable linking like
| [Hello](../hello.md) and resolve the link at build time,
| instead of expecting everyone to type [Hello](/why/hello/). And
| yet the popular ones I've used or looked at don't do this.
|
| It seems to be a marmite feature (you love it or you don't):
| I've raised it with static site builder team members and
| received a "Why would you want that?" response. Explanations
| got nowhere. I'm not sure if it's a niche feature, you have to
| have experienced the problem to appreciate the solution, or
| people are used to writing once and not maintaining for a
| decade or longer, but it'd be great to see wider support.
| throw310822 wrote:
| Ok, what about DITA?
| mixmastamyk wrote:
| I liked it as well. But many years ago I tried to get them to
| implement parts of a book, and they never did. You can work
| around somewhat by hardcoding chapter numbers--but I don't feel
| sphinx is suitable for book-length docs without that simple
| feature.
| dlivingston wrote:
| If you want Sphinx to achieve that breakout success, priority
| #1 should be to get high-quality, beautiful themes.
|
| At least for me, aesthetics are a high-priority factor when
| deciding which site generator to use. Hugo and Gatsby have
| great built-in themes, and I have chosen them for projects
| before based largely on this fact.
|
| The Sphinx themes here [0] and here [1] are various levels of
| "meh" to bland.
|
| Look at the standard Sphinx RTD theme: https://sphinx-rtd-
| theme.readthedocs.io/en/stable/
|
| Now, compare it to documentation sites like:
|
| - Apple's:
| https://developer.apple.com/documentation/swift/array
|
| - Fluent UI: https://react.fluentui.dev/?path=/docs/concepts-
| developer-po...
|
| RTD looks dated in comparison.
|
| [0]: https://sphinx-themes.org/
|
| [1]: https://sphinxthemes.com/#featured-themes
| 0xedd wrote:
| Looking at Fluent UI VS featured-themes, I don't see a
| difference.
|
| I'll ignore Apple because: 1) It loads _extremely_ slowly
| (10+ seconds). 2) Just looks like a dark theme and nothing
| more.
| dlivingston wrote:
| Apple's site loads for me in under 1 second with a clean
| cache force-reload.
|
| The featured themes, in general, have poor typography and
| whitespace, poor formatting and alignment, and uninspired
| colors and design. Furo [0] is the best-designed of them
| and would make a solid foundation for a proper theme.
|
| [0]: https://sphinxthemes.com/themes/furo
| kelsey98765431 wrote:
| 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.
| blt wrote:
| 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".
| betaby wrote:
| asciidoc anyone?
| schaefer wrote:
| 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 wrote:
| +1. My current workaround is the use of asciidoctor to
| convert my docs to docbook. This format is supported by
| pandoc.
| joekrill wrote:
| 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 wrote:
| 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 wrote:
| Sphinx + markdown (Myst) is a nice middle ground here I think,
| with the sphinx directives implemented as code blocks.
| karaterobot wrote:
| 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 wrote:
| > 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| the toc macro on asciidoc is sublime
|
| :table-caption!: :toc: macro :sectlinks:
|
| toc::[]
| FartinMowler wrote:
| I run asciidoctor's Docker container. It does what I want it
| to do without leaving a mess behind on my laptop.
| IshKebab wrote:
| The trouble with that is it becomes a pain in CI. Nested
| Docker isn't fun.
| IshKebab wrote:
| 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
| 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.
| YakBizzarro wrote:
| Oh yes, I could mot agree more. We moved from Antora/asciidoc
| to mkdocs/markdown. Overall the situation improved (better
| HTML, faster builds, syntax highlighting of code,...) but I
| miss how good writing in asciidoc was
| keybored wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| Why is your username not capitalized, Keybored?
| keybored wrote:
| Poor self-esteem.
| wodenokoto wrote:
| 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 wrote:
| > 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 wrote:
| 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 wrote:
| 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_ wrote:
| 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 wrote:
| This is why MDX rocks. It doesn't have all of this builtin, but
| you get a lot of the same benefits.
| somat wrote:
| "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 wrote:
| 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 wrote:
| 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 wrote:
| I believe Mozilla uses rstcheck for linting, and it's actively
| supported.
|
| https://github.com/rstcheck/rstcheck
| Animats wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| photonthug wrote:
| 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 wrote:
| 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
| photonthug wrote:
| 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.
| paholg wrote:
| That's what I meant by instructions on automated
| deployments. MdBook generates HTML, so you don't need
| anything fancy to host it.
|
| This example shows a fairly short GitHub action to deploy
| to GitHub pages: https://github.com/rust-
| lang/mdBook/wiki/Automated-Deploymen...
| runningmike wrote:
| 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/ and use Jupyterbook, which builds upon
| spinhx.
| JoshTriplett wrote:
| 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 wrote:
| 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
| KronisLV wrote:
| 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/ for the more
| standalone use cases.
| 8organicbits wrote:
| > 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-sh...
| RomanPushkin wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| Yes, and this sucks.
| remram wrote:
| 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 wrote:
| > 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 wrote:
| 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.
| Arainach wrote:
| >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.
| pclmulqdq wrote:
| 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 wrote:
| 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._...
|
| 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.
| conaclos wrote:
| Maybe Typst (https://typst.app/) is a good in-between?
| josephg wrote:
| I used typst for a recent project and I love it. It's
| essentially all the power of latex but with modern
| sensibilities. And it's a cute little programming language
| - with support for variables, functions, json data loading,
| 3rd party libraries, and all sorts of other nice to haves.
|
| I just wish the typst compiler had a way to output html. It
| would be perfect for making online documentation and blog
| posts.
| g8oz wrote:
| Indeed, I don't see the reason for someone to learn LaTex
| now that Typst is here.
| nrr wrote:
| "The second biggest issue is that there isn't a good TeX ->
| HTML compiler." This is the crux of the problem in using just
| TeX for writing books: it focuses on producing camera-ready
| output at the expense of literally everything else.
|
| reStructuredText isn't itself a typesetting language. It's
| meant to be something of an interposer between the semantic
| meaning of what you're writing and the thing that does the
| typesetting. The hope is that it, unlike something heavily
| constrained like Markdown, gives you the tools to capture
| that semantic meaning and transform it into something that
| can be typeset.
|
| Like, the goal isn't to throw out TeX. The goal is to be able
| to target TeX as a typesetter along with Web browsers and
| e-book readers and even things like GNU info and troff
| without having to rewrite the content wholesale to fit each
| one.
| pclmulqdq wrote:
| Personally, I would rather just have TeX itself target the
| web rather than wedging another layer into the typesetting
| stack. As far as I know, other than the sheer size of the
| language, there is nothing fundamental stopping someone (I
| guess me, eventually) from writing "htmlatex."
|
| Modern web pages are already designed with "camera ready"
| in mind, essentially with browser width being the only
| thing that changes layout.
| nrr wrote:
| My point is more that TeX is a typesetter just as a Web
| browser is. They're incompatible typesetting systems with
| wildly different command languages.
| bitwize wrote:
| TeX is old and busted; Typst is the new hotness. Written in
| Rust, too!
| bilater wrote:
| yup - my knee jerk reaction at seeing the first couple of
| samples was to recoil. Great if it works for ppl but I'm gonna
| stick with markdown.
| bityard wrote:
| I thought Markdown was clearly very silly back when it started
| gaining traction amongst developer types. There were already so
| many other better options--even at the time--for plaintext-to-
| formatted document markup languages.) But still, developers
| were designing whole apps (CMSes, productivity apps, document
| management, etc) and plugins around Markdown, sometimes as
| businesses.
|
| But then I realized, after using it in some apps, that wasn't
| really what Markdown was about. Markdown is about a bare-
| minimum amount of styling that is just as readable and at home
| in plaintext as formatted in HTML. The amount of formatting it
| supports is small _on purpose_, so that it fits in your brain
| and doesn't require a toolbar to use. It is _meant_ for things
| like comment fields, chat programs, commit messages, and so on.
| Maybe even blog articles. But it certainly is not something
| you'd want for writing the documentation for an enterprise-
| grade product.
|
| These days, I write Markdown even in place where it will never
| be rendered into HTML. Because it's quite readable as-is. (And
| I wish HN supported it.)
| packetlost wrote:
| > But it certainly is not something you'd want for writing
| the documentation for an enterprise-grade product.
|
| I guess that depends. If you're making a print manual, yeah
| probably not. IME markdown gets painful as soon as you start
| doing a bunch of tables.
|
| Most enterprise _web applications_ would probably be
| completely fine with just markdown-based docs.
| paholg wrote:
| I think a good example is all of the wonderful
| documentation that's been created with mdBook.
|
| Heck, the Rust book was written with it, and they also made
| a print edition, so maybe markdown is enough even for that.
|
| https://github.com/rust-lang/mdBook
| steveklabnik wrote:
| Carol put in a tremendous amount of work to build tooling
| to go between Markdown and Docx. The publishers used the
| docx versions for print.
|
| That doesn't mean that I think Markdown is inadequate or
| the wrong decision, but it's not just a "write in
| Markdown and you're good" sort of situation.
| paholg wrote:
| Ah, good to know! Is that tooling public anywhere, or was
| it pretty tailor-made just for the Rust book?
| steveklabnik wrote:
| Both public and tailor-made: https://github.com/rust-
| lang/book/tree/main/tools
| paholg wrote:
| Awesome! You and Carol rock!
| steveklabnik wrote:
| Thanks! She gets 100% of the credit in this case though
| :)
| tetha wrote:
| I arrived at a similar conclusion, just from the other
| direction: It is really hard to get people to document. It is
| even harder to get those people to care a little bit about
| formatting.
|
| Markdown is... limited, I acknowledge. But with a very small
| amount of learning, markdown is as fluent and simple to write
| as normal text. In fact, 90% of what I wrote before I knew
| markdown was valid and decently formatted markdown already.
|
| If you asked people who don't document to document in rST or
| tex... then you'd have no documentation at all. Because that
| suddenly adds a lot of effort on top of what you want to
| write down.
|
| Now for some customer-facing whitepapers and documentation,
| we do use rST. But there you have people who are tasked with
| paying some effort to create some decently looking docs. Not
| trying to coax developers into writing down some of their
| state of mind while doing stuff.
| unethical_ban wrote:
| Yes!
|
| Markdown is great because it is a way to write and store
| documentation in plaintext, in a way non-documentarians can
| follow.
| duskwuff wrote:
| And it's been making a ton of headway even outside that
| context -- I've seen occasional formatting goofs in
| online newspaper articles that indicated they were
| authoring their content in Markdown. (Which makes sense!
| News rarely requires complex formatting.)
| zelphirkalt wrote:
| Although, I have to say, it is a sad state of afairs, if
| rST is already too difficult for a person with the job role
| "programmer" to use. If this is already the threshold,
| which would stop them from writing documentation, then I
| have my doubts about the quality of documentation, that
| they will write in Markdown.
| fireflash38 wrote:
| Agreed. Mandate function docstrings? You'll get "Function
| FlargleBlab blabs the flargle" docstrings. Just useless.
| keybored wrote:
| Markdown is like a virus of an idea:
|
| 1. Apparently simple enough to implement to get the basics
| right (not that I could do it)
|
| 2. But there is plenty of room for accidental edge cases in
| the implementation
|
| 3. Many then implement it with or without edge cases
|
| 4. But it's not enough because a lot of the people who use it
| are _programmers_ so they naturally want to extend it to do
| just a little more
|
| 5. Now the standardization effort (Commonmark) has to take
| all of those edge cases into account plus have to figure out
| how to deal with extensions (especially for popular ones)
|
| 6. Then you get a heroically (in terms of effort and grit)
| wordy standard
|
| All for the initial idea which is so simple that it seems
| redundant: look as good plain as rendered. (Then what's the
| point of rendering it, and in turn what's the point of a
| formal syntax instead of the (still existing) ad hoc email
| and whatnot conventions?)
|
| Right now it's fantastic for chat applications (here you
| definitely want rendering and not the visible markup). It's
| been pretty good for things like forum comments as well. With
| the exception of block quotes which are a pain to fiddle with
| (the only prefix syntax if you don't include the indentation-
| for-code since that is de facto optional now that so many
| applications support code fences... all because that's how
| email does it).
| bitwize wrote:
| Markdown is the Unix of rich text formats.
| rcarmo wrote:
| Yeah, I still have thousands of Textile pages, but all of my
| newer stuff is in Markdown...
| hinkley wrote:
| As we've gone horizontal on tool chains instead of vertical
| like we used to, what you want is a bunch of mentally cheap
| tools with high bang for the buck. Get in, get out, move on
| to the next of fifty tools you have to deal with each week.
| tjoff wrote:
| > _Markdown is about a bare-minimum amount of styling that is
| just as readable and at home in plaintext as formatted in
| HTML._
|
| My gripe is that it really isn't. Because markdown inevitable
| includes images or something and the instant it does it
| doesn't hold up to it's killer feature. Now you can't read it
| properly, so now you have to find a generated version, or
| hunt down the images manually, or generate the output
| yourself.
|
| Alternatively, the document is so trivial that even markdown
| formatting is too much (just distracts) and doesn't add
| anything of value.
|
| It isn't that bad, it just never seems to make any sense for
| files. It does make sense for web forms though but that's
| only because you never read the markdown, you just write it
| and the output is generated on the fly.
| 8organicbits wrote:
| When you use one of the extensions, like Hugo's figure,
| which has alt-text support you're about as close to that
| goal as possible. An image can't be stored in human
| readable plain text.
|
| The alternative is WYSIWYG formats that aren't plain text.
| tjoff wrote:
| Doesn't matter how close to the goal you get if it is on
| the outside...
|
| I'm gonna be annoyed if I clone your repo, open the
| readme.md and now have to figure out how to read it.
|
| Plain text is awesome, for plain text. If it isn't plain
| text might as well use a pdf.
| 8organicbits wrote:
| There's no reason for this to be all or nothing. This
| seems perfectly readable to me: 
|
| Even if you've never seen markdown before, it's pretty
| obvious.
| edgarvaldes wrote:
| The very next paragraph in TFA agrees with you:
|
| >...Okay yeah that's actually a pretty good reason not to use
| it. I can't get into lisps for the same reason. I'm not going
| to begrudge anybody who avoids a tool because it's ugly.
| thomascgalvin wrote:
| I _have_ used markdown to write books, and it worked just fine.
| Now, these were novels, not technical documents, but I never
| encountered something that couldn 't be solved with markdown
| plus some occasional HTML.
|
| I've also generated quite a bit of technical documentation
| using markdown, and Pandoc's extensions[1] allow you to include
| pretty much any formatting you might require, complicated math
| and syntax highlighted code blocks included.
|
| That markdown can then be transformed into HTML, a Word doc, a
| ePub, a PDF ...
|
| There needs to be a _very_ compelling reason for me to reach
| for something other than markdown.
|
| [1] https://pandoc.org/MANUAL.html
| bluGill wrote:
| Most novels don't need anything more complex than a link to
| the next chapter at the end of the page. Maybe bold text, but
| a lot get by without. As such markdown will work for most.
| I've seen some novels with some really complex formatting,
| but those are rare (I read a lot of litRPG and still call
| them rare). However I mostly write technical documentation
| and I often hit limits of things markdown cannot do even
| though my documents are much shorter than a novel.
| zelphirkalt wrote:
| Pandoc is a great thing! However, lets not mix up Pandoc
| Markdown with standard Markdown. Pandoc Markdown
| intentionally adds features, that make it more suitable for
| academic writing, I believe.
| sureglymop wrote:
| And it actually can be easily extended with custom blocks ( :::
| ). https://github.com/vokimon/markdown-customblocks
| ajross wrote:
| > 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.
|
| I'd go so far as to flip those two. By far, it's more important
| to ensure that documentation _can be easily written_ (the
| raisin d 'etre of MD) than it is to optimize for the job of the
| people trying to collate/edit/format/improve/maintain the
| documentation (something that RST speaks to, primarily).
|
| Because the primarily failure mode in this space is _not_ that
| we have imperfectly edited documentation. _It 's that we lack
| docs at all, because the hackers didn't understand the doc
| tools_.
|
| In Zephyr, we use RST. And... it's fine. I've made my peace
| with it. But "please write some docs" is a routine comment in
| review, and in my experience many-probably-most contributors
| just don't know how and don't want to take the time to learn.
| The barrier to markdown would be much, much lower.
| philistine wrote:
| > I don't want to write a book. If I did I'd use LaTeX before
| RST.
|
| 100 times yes. Markdown for light styling. LaTeX for anything
| else. The next revolution in standardized text parsers will not
| come from replacing Markdown, but from replacing LaTeX.
| qwerty456127 wrote:
| > Because the biggest advantage of Markdown is that it's easy
| to read
|
| Do you really read Markdown in plain text editors? I only do
| occasionally (nevertheless I'm glad I can). Most of the times I
| use tools like Obsidian, Typora, Markdown Monster etc.
|
| HTML is just _too_ bad for plain source reading relatively to
| Markdown and too complex for reliable mapping between what it
| is looks, what it means and what it is.
|
| This said, something slightly more complex than Markdown while
| slightly more elegant, less chaotic and more readable than HTML
| sounds a great thing to have.
|
| There certainly are cases where Makrdown seems the best choice
| - wherever simple plaintext editors are going to be used often.
| Nevertheless I doubt Markdown is the best choice for tools like
| Obsidian - perhaps people working on new projects of this kind
| should also take a look at rST or AsciiDoc.
| riidom wrote:
| I'm with you on that, I can think of one counter example
| though, and that is when you have to write your MD in
| something like VS Code. Which uses the old-fashioned approach
| of source code pane and render pane. I strongly dislike that
| and usually try to get away with source-code view only. To be
| fair, they use a tiny bit of coloring, so it's not 100% plain
| text. And the better solution is to write your MD in any
| other MD editor except VSC, of course.
| qwerty456127 wrote:
| > I don't want to write a book. If I did I'd use LaTeX before
| RST.
|
| To me this seems a horrible decision at the stage of
| writing/structuring. I'd rather write in Markdown (this way I
| could just write, without bothering about typesetting) and only
| convert to LaTeX for publishing. I'm not proficient in LaTeX
| though - I once tried to learn it and it felt like learning a
| language of an insectoid extraterrestrial civilization -
| completely unintuitive, almost impossible to do anything new -
| what hasn't been already done by someone else enabling you just
| copy-paste your own text. IIRC it doesn't even have first-class
| Unicode support.
| anserin wrote:
| In LaTeX you also clearly separate structure and typesetting:
| you don't write
| \noindent\textbf{Introduction}\nobreak\medskip or whatever,
| but simply \section{Introduction}
|
| Macros are also pretty easy to define
| \newcommand\important[1]{\textcolor{red}{#1}}
|
| And of course it has first-class Unicode support
| josephg wrote:
| Easy is relative. Latex is sooo much uglier than typst:
| #let important(body) = { text(red, body)
| } But whatever you do, #important[Dont
| *panic*!]
|
| Docs:
|
| https://typst.app/docs/reference/foundations/function/
| nrr wrote:
| "In LaTeX you also clearly separate structure and
| typesetting ..." Not quite.
|
| The rub comes in when you want to pull that content out to
| render it in a format that isn't meant to be camera-ready,
| like a Web page or an e-book. TeX, even with Leslie
| Lamport's LaTeX macros, doesn't give you an ergonomic
| mechanism for marshalling out the semantic structure of
| your document to reuse elsewhere.
|
| You're left parsing the TeX yourself, and that sucks.
| ori_b wrote:
| Yes, that is a good rephrasing of the rest of the paragraph you
| quoted.
| eviks wrote:
| > 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.
|
| That's not true, even at the basics it's not great, let alone
| the best: asterisks/underlines for italics already require
| familiarity unlike the much more intuitive /italic slashes/
|
| And then outside the basics it's not that easy to write/read
| either, you'll get lost in bad formatting of tables or metadata
| (tags) obscuring text or what not without proper tooling
|
| > How easy it is to extend is largely irrelevant
|
| It is relevant as then you could fix those basics if you could
| easily and conveniently extend it
| necovek wrote:
| Uhm, reST is also easy to read and write, at least where
| Markdown is easy to read and write.
|
| To me, they are largely the same thing, with slight syntax
| differences, with reST being more readable as it's clearer what
| any special syntax is about, whereas MD is more concise to type
| out -- you need to learn the special syntax whatever way you
| slice it.
|
| FWIW, reST was the default for Python "doctests": a wonderful
| feature that has fallen out of favour for some reason, but has
| the potential to be your real runnable documentation.
|
| I wouldn't write a book in either, but that's because I am
| really high on great typesetting -- I even had my own set of
| (Plain) TeX macros to do ToC generation, syntax highlighting,
| alternative math fonts, support for UTF-8 before eTeX and such
| when I did write papers and handed in coursework regularly.
| bosie wrote:
| What do you use for the actual, non-quick documentation?
|
| Markdown is pretty bad for note taking, it has a niche
| functionality suited for basic text based note taking.
| Unfortunately that isn't the only note taking that is possible
| andrepd wrote:
| This is pretty much the paragraph that follows the paragraph
| you cited...
| skybrian wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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/
|
| 2. https://docs.racket-lang.org/pollen/
| nailer wrote:
| "Now here's how to make an image in rst:" ..
| image:: example.jpg :alt: alttext
|
| Great, I can close this article now.
| taeric wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| I prefer What You See Is What You Get (WYSIWYG.)
| beej71 wrote:
| 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 wrote:
| 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 wrote:
| > 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/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 wrote:
| > 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 wrote:
| > ...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 wrote:
| 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 wrote:
| 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 wrote:
| What's the YAML syntax for "That's a _weird_ idea,
| [YAML](https://yaml.org/) is a data serialization language"?
| hintymad wrote:
| > .. 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 wrote:
| 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 wrote:
| 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 wrote:
| I think author should write HTML if they want extensibility so
| much. Not like RST is reading-friendly to begin with.
| innocentoldguy wrote:
| 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 wrote:
| 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.
| ktosobcy wrote:
| 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 wrote:
| 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
|
| My team maintained https://userdocs.rapyuta.io in markdown for
| the last 4 years. https://github.com/rapyuta-robotics/rapyuta-io-
| docs
|
| - we also maintained https://sdk.rapyuta.io/ &
| https://cli.rapyuta.io/ both in semiautomated rst + github
| actions setup
| zelphirkalt wrote:
| 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 wrote:
| 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.
| johnmaguire wrote:
| 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 wrote:
| 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#..., 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".
| johnmaguire wrote:
| I'm not arguing one is better, just that Markdown is
| simpler: it literally has less syntax. If I don't need all
| the bells and whistles of reST, Markdown is simpler to
| learn, use and likely implement.
|
| I agree that reST is probably a better fit for complex use
| cases like building a docs site. But it's overkill for
| Facebook Messenger or even forum posts, IMO.
| necovek wrote:
| I am arguing that it's not simpler either. Check out the
| latest spec on Markdown:
| https://spec.commonmark.org/0.31.2/
|
| If you want to use a mark-up language in a chat app, a
| subset of either would serve you just fine and both are
| equally simple. It sounds like you are comparing a subset
| of what-is-markdown-today (and there are still variants)
| to full reST, which I don't think is a fair comparison.
| fireflash38 wrote:
| 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.
| fridder wrote:
| 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 wrote:
| 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.
___________________________________________________________________
(page generated 2024-07-31 23:00 UTC)