MyST 和 CommonMark 的关系，及学习课程 （**）

现在（2023）使用网络文档 md 格式，或多或少都还有带有一点程序员的味道。

这对于单纯的写作者来说，这是一种负担。未来应该像 word 那样，比如 typora 那样，写作者不需要了解 md 语法就可以写作了吧？

MyST Quickstart Tutorial：

  https://mystmd.org/guide/quickstart-myst-websites

  https://mystmd.org/guide/quickstart-myst-markdown

MyST 语法：https://studynotes.readthedocs.io/zh/main/struct/MyST/myst-index.html

MyST Markdown 概述：https://daobook.github.io/jupyter-book-zh/content/myst.html

------

 CommonMark 学习课程：

  https://commonmark.org/help/

  https://commonmark.org/help/tutorial/

  https://www.markdownguide.org/extended-syntax/

 

typography：排字式样；印刷(术)；印刷品；字体排印学

一. MyST 是 CommonMark Markdown 的一个（种）扩展。

MyST：  https://myst-parser.readthedocs.io/en/latest/intro.html

CommonMark：  https://commonmark.org/

官网原文：MyST is an extension of CommonMark Markdown, that includes a rich additional syntax for technical authoring, and can integrate with Docutils and Sphinx.

For example, MyST includes role and directive extensions points, to allow for richer features, such as admonitions and figures.  https://myst-parser.readthedocs.io/en/latest/intro.html

​说明：

1. 在 MyST 文档中，可以包含 CommonMark Markdown 格式。但还包含了扩展部分的内容，如“规则”和“指令”，这些丰富和扩展了网络文档的排版结构和能力。

2. 可以使用 CommonMark 来编辑 MyST Markd文档，但需要注意的是：非 CommonMark格式的部分，在通用 CommonMark编辑器中，将以文本（？）的形式出现，不会被正确地预览 preview。

3. 正确预览 MyST 文档，目前暂时只能在 MyST 官方网站上进行实时在线预览。

这种做法只适合与学习和验证；并不适合在日常创作中进行使用。

对于 CommonMark 来说，pycharm 属于单机使用版，是强大的，也是收费的。
pycharm 也可以实现部分 restructuredtext 文档的实时预览功能，但是，专有的“规则”和“指令”部分，则不能实现实时预览，只是以文本形式出现。或许需要经过某种配置才行吧？没有再做尝试了。

4. 理解 MyST 和 CommonMark 的区别和联系的好处：CommonMark 编辑器可选择的种类多，方便选用。而 MyST 编辑器则很少，在 VScode中有官方给出的编辑器，但版本可能太旧了？

5. Sphinx 和 MKdocs是同一类产品：

5.1. .rst /.md -->> 文件格式处理 api （ Sphinx / MKdocs） -->> theme 排版界面网站场景主题 -->> 输出 pdf /html -->> 浏览器

5.2. 如何选择？

选用 MyST，格式种类多，难记忆，更适合专门从事文档排版的人员使用。

因此，普通创作用户，需要自己将 MyST专有格式 和 CommonMark 通用格式分开，这样才有可能将 MyST 分成复杂格式和简单格式。

复杂格式只要一次性设置好了即可。

简单格式部分，即 CommonMark 部分，这才是日常创作所要经常使用的。

这样处理的好处，方便记忆和使用。

------

选用 MKdocs，格式种类少，实现功能简单，需要通过更多的 html标签来进行扩展。专门的开发工具似乎比 MyST要少（2023）？

  https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown

  https://daringfireball.net/projects/markdown/

6. 选择 restructuredtext ？还是 Markdown ？

restructuredtext 更适合专门从事文档排版的人员使用。

rst 的格式形式，不如 Markdown。缤纷的格式符号，有时会掩盖掉真正的内容。

因此，对于创作者，而非排版者来说，Markdown 显得简洁的多，不会被缤纷的格式标签符号，扰乱思考和思路。

7. 网络时代的进步，使得网络文档，成为一种新型的创作模式。

网络文档，同时具备了在网站中显示（html），以及电子图书导出（如 pdf .docx）等等的功能。

之前流行的 单机版 Word 编辑器，功能强大，但网站显示功能没有，只有网页显示功能。

Word 等网页显示功能，只是可以实现单一网页的显示。

而网站显示，则需要处理好各个单一网页之间的层次，以及其他链接等等的关系。

这类工具目前（2023）还处在上升阶段的活跃期，新陈代谢，诸侯争霸的阶段。

8. 开源，免费，不等于可以随意使用，是有约束条件的。

目前有不少优秀的 Markdown 编辑工具，用户并不是可以随便去使用它们。比如：Joplin，Zotero，它们是跟网站绑定的，没有开放出本地保存的功能（没有保存在本地的菜单），只能保存在规定的网站中。

虽然它们有导入导出功能，但是，当两次导出为相同文件夹时，文件会被重命名。不会覆盖掉旧版本，因此，似乎不适合用于日常编辑。

Typora：有“保存”，“另存为”功能，但这是要收费的。

离线的单机开发工具，目前似乎哪一个都还不完善？

MyST：  https://myst-parser.readthedocs.io/en/latest/intro.html

  https://mystmd.org/

CommonMark：  https://commonmark.org/

MyST 在线编辑和预览工具：

简易  https://mystmd.org/

全面  https://myst-parser.readthedocs.io/en/latest/live-preview.html

原文：

🚀 MyST Markdown Get Started

   https://myst-parser.readthedocs.io/en/latest/intro.html

This page gives a quick overview of how to get started with MyST Markdown, and how to use it within Docutils and Sphinx.

1.  Installation

To install myst-parser use pip:

pip install myst-parser

or Conda:

conda install -c conda-forge myst-parser

2.  Write a Markdown document

To start off, create an empty file called example.md and give it a Markdown title and text. We can now use the myst-docutils-demo CLI tool, from the installed package, to parse this file to HTML:

myst-docutils-demo example.md 

# My nifty title

Some **text**!

<section id="my-nifty-title">
<h1>My nifty title</h1>
<p>Some <strong>text</strong>!</p>
</section>

3.  Extend Markdown with MyST syntax

MyST is an extension of CommonMark Markdown, that includes a rich additional syntax for technical authoring, and can integrate with Docutils and Sphinx.

For example, MyST includes role and directive extensions points, to allow for richer features, such as admonitions and figures.

Lets add an admonition directive and sup role to your Markdown page, like so:

myst-docutils-demo example.md --myst-enable-extensions=colon_fence

# My nifty title

Some **text**!

:::{admonition} Here's my title
:class: tip

Here's my admonition content.{sup}`1`
:::

<section id="my-nifty-title">
<h1>My nifty title</h1>
<p>Some <strong>text</strong>!</p>
<aside class="admonition tip">
<p class="admonition-title">Here's my title</p>
<p>Here's my admonition content.<sup>1</sup></p>
</aside>
</section>

Tip

MyST works with just about all Docutils and Sphinx roles and directives.

Note, Sphinx provides a superset of the Docutils roles and directives, so some may not work in the Docutils CLI.

4.  Cross-referencing

MyST-Parser offers powerful cross-referencing features, to link to documents, headers, figures and more.

For example, to add a section reference target, and reference it:

myst-docutils-demo example.md 

(header-label)=
# A header

[My reference](#header-label)

<section id="a-header">
<span id="header-label"></span><h1>A header</h1>
<p><a class="reference internal" href="#header-label">My reference</a></p>
</section>

5.  Enable MyST in Sphinx

To get started with Sphinx, see their quick-start guide.

To use the MyST parser in Sphinx, simply add the following to your conf.py configuration file:

extensions = ["myst_parser"]

This will activate the MyST Parser extension, causing all documents with the .md extension to be parsed as MyST.

Our example.md file can now be added as the index page, or see the organising content section about creating toctree directives, to add example.md to.

Tip

There are a range of great HTML themes that work well with MyST, such as sphinx-book-theme (used here), pydata-sphinx-theme and furo

6.  Configuring MyST-Parser

The Configuration section contains a complete list of configuration options for the MyST-Parser.

These can be applied globally, e.g. in the sphinx conf.py:

myst_enable_extensions = ["colon_fence"]

Or they can be applied to specific documents, at the top of the document, in frontmatter:

---
myst:
  enable_extensions: ["colon_fence"]
---

7.  Extending Sphinx

The other way to extend MyST in Sphinx is to install Sphinx extensions that define new roles, directives, etc.

For example, let’s install the sphinx-design extension, which will allow us to create beautiful, screen-size responsive web-components.

First, install sphinx-design:

pip install sphinx-design

Next, add it to your list of extensions in conf.py:

extensions = [
  "myst_parser",
  "sphinx_design",
]

Now, we can use the design directive to add a web-component to our Markdown file!

:::{card} Card Title
Header
^^^
Card content
+++
Footer
:::

Header

Card Title

Card content

Footer

::::{tab-set}

:::{tab-item} Label1
Content 1
:::

:::{tab-item} Label2
Content 2
:::

::::

Label1

Content 1

Label2

There are many other great Sphinx extensions that work with MyST, such as the ones used in this documentation:

sphinx-design:
Add beautiful, responsive web-components to your documentation

sphinx-copybutton:
Add a copy button to your code blocks

sphinxext-rediraffe:
Add redirects to your documentation

sphinxext-opengraph:
Add OpenGraph metadata to your documentation

sphinx-pyscript:
Execute Python code in your documentation, see here

sphinx-tippy:
Add tooltips to your documentation, see here

sphinx-autodoc2:
Generate documentation from docstrings, see here

sphinx-togglebutton:
Add collapsible content to your documentation

sphinxcontrib.mermaid:
Generate Mermaid diagrams

See also

sphinx-extensions, for a curated and opinionated list of Sphinx extensions.

：https://myst-parser.readthedocs.io/en/latest/intro.html