News for hackers. Stuff that matters.
Re:Myst Markdown – Markdown for technical/scientific document by zelphirkalt on Sunday January 05, 2025 @08:11AM (#42601507)
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.

Re:Myst Markdown – Markdown for technical/scientific document by everybodyknows on Sunday January 05, 2025 @11:37AM (#42602923)
Org-mode has a new maintainer, and he has invited contributions of source code:

https://emacsconf.org/2024/talks/org-update/

Re:Myst Markdown – Markdown for technical/scientific document by zelphirkalt on Sunday January 05, 2025 @08:17PM (#42606589)
Yeah, 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.
Re:Myst Markdown – Markdown for technical/scientific document by jgruber on Sunday January 05, 2025 @02:04PM (#42604094)
> there is great potential to have finally good documentation

Yes, true, no good documentation has ever been written in Markdown. Good point.

Re:Myst Markdown – Markdown for technical/scientific document by gwern on Sunday January 05, 2025 @02:50PM (#42604460)
Most 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
Re:Myst Markdown – Markdown for technical/scientific document by lima on Tuesday January 07, 2025 @05:52AM (#42621252)
> 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)
Re:Myst Markdown – Markdown for technical/scientific document by agoose77 on Tuesday January 07, 2025 @10:07AM (#42623118)
This 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-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) and cross-referencing (https://mystmd.org/guide/cross-references)

Re:Myst Markdown – Markdown for technical/scientific document by thadguidry on Wednesday January 08, 2025 @01:54AM (#42631721)
One 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 Which allows supplying a list of external references, and complete metadata: https://mystmd.org/guide/website-metadata#myst-xref-json