3 ms·
As a notorious Markdown critic, I have to say, their syntax really looks like a decent attempt of support for technical and scientific documents. Having used re
by zelphirkalt 2y ago
As a notorious Markdown critic, I have to say, their syntax really looks like a decent attempt of support for technical and scientific documents. Having used reStructuredText for a thesis with a lot of bells and whistles, and having used org-mode mostly ever since, I am not just admitting it willy-nilly. Then of course some of its syntax and syntax concepts are straight out of reStructuredText's book, so it makes sense, that it would inherit the capabilities as well.
What I haven't seen at a quick glance is the ability to link to any place in the document (sink) from withing the document itself (source). Maybe I did not look far enough in the examples. reStructuredTex can do this, and org-mode can do that too. And I don't mean just linking to existing headings. The other required things like footnotes and citations and so on seem to be there. Now if this reaches mainstream and we start writing documentation in it, there is great potential to have finally good documentation, not limited by the likes of github markdown. Of course same is true for reStructuredText and org-mode. From that perspective, one could ask, why yet another format was necessary, rather than improving tooling for lets say reStructuredText.
- everybodyknows 2y agoOrg-mode has a new maintainer, and he has invited contributions of source code: https://emacsconf.org/2024/talks/org-update/ https://emacsconf.org/2024/talks/org-update/
- zelphirkalt 2y agoYeah, I have seen the talk! He already reviewed some change I once sent and some bug report. Was very responsive and also gave me hints for what part I would need to change to make a specific thing happen. Very helpful.
- jgruber 2y ago> there is great potential to have finally good documentation Yes, true, no good documentation has ever been written in Markdown. Good point.
- gwern 2y agoMost Markdown dialects will support some sort of label or 'span' naming, which provides link targets (if only by dropping down to literal HTML <span>/<div> elements), and it looks like this does too: https://mystmd.org/guide/cross-references#label-anything https://mystmd.org/guide/cross-references#label-anything
- lima 2y ago> What I haven't seen at a quick glance is the ability to link to any place in the document (sink) from withing the document itself (source). You can create an anchor: (my-anchor)= ...and then link to it: [see here](#my-anchor) (https://mystmd.org/guide/cross-references https://mystmd.org/guide/cross-references)
- agoose77 2y agoThis is a lovely comment to read, thank you. The only implementation of restructured text is the docutils-Sphinx ecosystem. MyST Markdown was designed as a nicer language for Markdown-familiar authoring: https://executablebooks.org/en/latest/blog/2020-08-07-announce-book/#an-enhanced-flavor-of-markdown https://executablebooks.org/en/latest/blog/2020-08-07-announ... In the myst-md project, we're applying many of the lessons that we learned in the Jupyter Book project. One of the big takeaways is that the tooling is equally as important as the underlying markup, and docutils/Sphinx was holding us back in a few areas. If you like links within documents, take a look at embedding (https://mystmd.org/guide/embed https://mystmd.org/guide/embed) and cross-referencing (https://mystmd.org/guide/cross-references https://mystmd.org/guide/cross-references)
- thadguidry 2y agoOne of the most powerful features that I pushed the MyST team to incorporate is xref (linking External MyST projects via borrowed syntax from ReStructuredText) https://mystmd.org/guide/external-references#myst-xref https://mystmd.org/guide/external-references#myst-xref Which allows supplying a list of external references, and complete metadata: https://mystmd.org/guide/website-metadata#myst-xref-json https://mystmd.org/guide/website-metadata#myst-xref-json