Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.



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


Org-mode has a new maintainer, and he has invited contributions of source code:

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


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.


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)


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


> there is great potential to have finally good documentation

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


> 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)




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: