📚 DOCS: Format docs with mdformat-myst #156

Original file line number	Diff line number	Diff line change
Expand Up		@@ -9,12 +9,19 @@ exclude: >
		test.*\.html\|
		test.*\.xml\|
		.*commonmark\.json\|
	benchmark/.*\.md\|
	benchmarking/.*\.md\|
		.*/spec\.md
		)$

		repos:

	- repo: https://github.com/executablebooks/mdformat
	rev: 0.7.4
	hooks:
	- id: mdformat
	args: [--number]
	additional_dependencies: [mdformat-myst==0.1.2]

		- repo: https://github.com/pre-commit/pre-commit-hooks
		rev: v3.4.0
		hooks:
Expand Down

32 changes: 17 additions & 15 deletions CHANGELOG.md

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -44,8 +44,8 @@ There are four notable (and breaking) changes:

		This release brings Markdown-It-Py inline with Markdown-It v11.0.1 (2020年09月14日), applying two fixes:

	- Fix blockquote lazy newlines, [[#696](https://github.com/markdown-it/markdown-it/issues/696)].
	- Fix missed mappings for table rows, [[#705](https://github.com/markdown-it/markdown-it/issues/705)].
	- Fix blockquote lazy newlines, \[[#696](https://github.com/markdown-it/markdown-it/issues/696)\].
	- Fix missed mappings for table rows, \[[#705](https://github.com/markdown-it/markdown-it/issues/705)\].

		Thanks to [@hukkinj1](https://github.com/hukkinj1)!

Expand Down Expand Up		@@ -135,27 +135,29 @@ md = MarkdownIt().use(tasklists_plugin)
		- ✨ NEW: Add simple typographic replacements, thanks to [@tsutsu3](https://github.com/tsutsu3):
		This allows you to add the `typographer` option to the parser, to replace particular text constructs:

	- ``(c)``, ``(C)`` → ©
	- ``(tm)``, ``(TM)`` → TM
	- ``(r)``, ``(R)`` → ®
	- ``(p)``, ``(P)`` → §
	- ``+-`` → ±
	- ``...`` → ...
	- ``?....`` → ?..
	- ``!....`` → !..
	- ``????????`` → ???
	- ``!!!!!`` → !!!
	- ``,,,`` → ,
	- ``--`` → &ndash
	- ``---`` → &mdash
	- `(c)`, `(C)` → ©
	- `(tm)`, `(TM)` → TM
	- `(r)`, `(R)` → ®
	- `(p)`, `(P)` → §
	- `+-` → ±
	- `...` → ...
	- `?....` → ?..
	- `!....` → !..
	- `????????` → ???
	- `!!!!!` → !!!
	- `,,,` → ,
	- `--` → &ndash
	- `---` → &mdash

		```python
		md = MarkdownIt().enable("replacements")
		md.options["typographer"] = True
		```

		- 📚 DOCS: Improve documentation for CLI, thanks to [@westurner](https://github.com/westurner)

		- 👌 IMPROVE: Use `re.sub()` instead of `re.subn()[0]`, thanks to [@hukkinj1](https://github.com/hukkinj1)

		- 🐛 FIX: An exception raised by having multiple blank lines at the end of some files

		## 0.5.5 - 2020年09月27日
Expand Down

22 changes: 10 additions & 12 deletions README.md

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
		@@ -1,6 +1,6 @@
		# markdown-it-py

	[![Github-CI][github-ci]][github-link]
	[![Github-CI]][github-link]
		[![Coverage Status][codecov-badge]][codecov-link]
		[![PyPI][pypi-badge]][pypi-link]
		[![Conda][conda-badge]][conda-link]
Expand Down Expand Up		@@ -127,22 +127,20 @@ Big thanks to the authors of [markdown-it]:

		Also [John MacFarlane](https://github.com/jgm) for his work on the CommonMark spec and reference implementations.

	[github-ci]: https://github.com/executablebooks/markdown-it-py/workflows/Python%20package/badge.svg?branch=master
	[github-link]: https://github.com/executablebooks/markdown-it-py
	[pypi-badge]: https://img.shields.io/pypi/v/markdown-it-py.svg
	[pypi-link]: https://pypi.org/project/markdown-it-py
	[conda-badge]: https://anaconda.org/conda-forge/markdown-it-py/badges/version.svg
	[conda-link]: https://anaconda.org/conda-forge/markdown-it-py
	[codecov-badge]: https://codecov.io/gh/executablebooks/markdown-it-py/branch/master/graph/badge.svg
	[codecov-link]: https://codecov.io/gh/executablebooks/markdown-it-py
		[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
		[black-link]: https://github.com/ambv/black
	[codecov-badge]: https://codecov.io/gh/executablebooks/markdown-it-py/branch/master/graph/badge.svg
	[codecov-link]: https://codecov.io/gh/executablebooks/markdown-it-py
	[conda-badge]: https://anaconda.org/conda-forge/markdown-it-py/badges/version.svg
	[conda-link]: https://anaconda.org/conda-forge/markdown-it-py
	[github-ci]: https://github.com/executablebooks/markdown-it-py/workflows/Python%20package/badge.svg?branch=master
	[github-link]: https://github.com/executablebooks/markdown-it-py
		[install-badge]: https://img.shields.io/pypi/dw/markdown-it-py?label=pypi%20installs
		[install-link]: https://pypistats.org/packages/markdown-it-py

	[CommonMark spec]: http://spec.commonmark.org/
		[markdown-it]: https://github.com/markdown-it/markdown-it
		[markdown-it-readme]: https://github.com/markdown-it/markdown-it/blob/master/README.md
	[md-security]: https://markdown-it-py.readthedocs.io/en/latest/other.html
		[md-performance]: https://markdown-it-py.readthedocs.io/en/latest/other.html
		[md-plugins]: https://markdown-it-py.readthedocs.io/en/latest/plugins.html
	[md-security]: https://markdown-it-py.readthedocs.io/en/latest/other.html
	[pypi-badge]: https://img.shields.io/pypi/v/markdown-it-py.svg
	[pypi-link]: https://pypi.org/project/markdown-it-py

4 changes: 0 additions & 4 deletions docs/architecture.md

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -40,7 +40,6 @@ An `env` sandbox can be used alongside tokens to inject external variables for y

		Each chain (core / block / inline) uses an independent `state` object when parsing data, so that each parsing operation is independent and can be disabled on the fly.


		## Token stream

		Instead of traditional AST we use more low-level data representation - tokens.
Expand Down Expand Up		@@ -73,7 +72,6 @@ More details about tokens:
		- [Token source](https://github.com/executablebooks/markdown-it-py/tree/master/markdown_it/token.py)
		- [Live demo](https://markdown-it.github.io/) - type your text and click `debug` tab.


		## Rules

		Rules are functions, doing "magic" with parser `state` objects. A rule is associated with one or more chains and is unique. For instance, a `blockquote` token is associated with `blockquote`, `paragraph`, `heading` and `list` chains.
Expand All		@@ -93,7 +91,6 @@ Also, in complex cases you can try to ask for help in tracker. Condition is very
		simple - it should be clear from your ticket, that you studied docs, sources,
		and tried to do something yourself. We never reject with help to real developers.


		## Renderer

		After the token stream is generated, it's passed to a [renderer](https://github.com/executablebooks/markdown-it-py/tree/master/markdown_it/renderer.py).
Expand Down Expand Up		@@ -157,7 +154,6 @@ renderer override, but can be more simple.
		You also can write your own renderer to generate other formats than HTML, such as
		JSON/XML... You can even use it to generate AST.


		## Summary

		This was mentioned in [Data flow](#data-flow), but let's repeat sequence again:
Expand Down

16 changes: 8 additions & 8 deletions docs/contributing.md

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -68,14 +68,14 @@ For documentation build tests:
		Where possible try to port directly from that.
		It is usually better to modify existing code, instead of writing all from scratch.
		2. Try to find the right place for your plugin rule:
	- Will it conflict with existing markup (by priority)?
	- If yes - you need to write an inline or block rule.
	- If no - you can morph tokens within core chains.
	- Remember that token morphing in core chains is always more simple than writing
	block or inline rules, if you don't copy existing ones. However,
	block and inline rules are usually faster.
	- Sometimes, it's enough to only modify the renderer, for example, to add
	header IDs or `target="_blank"` for the links.
	- Will it conflict with existing markup (by priority)?
	- If yes - you need to write an inline or block rule.
	- If no - you can morph tokens within core chains.
	- Remember that token morphing in core chains is always more simple than writing
	block or inline rules, if you don't copy existing ones. However,
	block and inline rules are usually faster.
	- Sometimes, it's enough to only modify the renderer, for example, to add
	header IDs or `target="_blank"` for the links.

		## FAQ

Expand Down

5 changes: 3 additions & 2 deletions docs/index.md

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -28,8 +28,9 @@ Also [John MacFarlane](https://github.com/jgm) for his work on the CommonMark sp
		- <http://talk.commonmark.org> - CommonMark forum, good place to collaborate developers' efforts.

		```{toctree}
	:maxdepth: 2

	---
Copy link Member @chrisjsewell chrisjsewell Apr 25, 2021 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. It would be nice if this did not convert from the short-hand Copy link Member @chrisjsewell chrisjsewell Apr 25, 2021 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. but mainly looking good cheers! Copy link Contributor Author @hukkin hukkin Apr 25, 2021 • edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. It would be nice if this did not convert from the short-hand Hmm, maybe. I couldn't see any crystal clear advantage to using the short-hand, besides maybe being one line less verbose. Always formatting with the frontmatter style has a few advantages: Kills useless debate in PRs about which style to use Removes the chance that you'll ever need to look at a frontmatter style to short-hand style diff (or vice-versa) in a PR --> cleaner diffs, simpler reviews. The syntax makes it more obvious that the content is, in fact, just plain YAML. but mainly looking good cheers! 🥳 Copy link Member @chrisjsewell chrisjsewell Apr 25, 2021 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. I couldn't see any crystal clear advantage to using the short-hand Well its more comparable to the RST syntax (to ease migration), but mainly I fear (like the consecutive numbering discussion) it may put users off using mdformat, if it enforces a style they are not used to (a lot of current documentation uses the shorthand), similarly I would envisage it as a flag Copy link Contributor Author @hukkin hukkin Apr 26, 2021 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. Consecutive numbering was different to me in that that style clearly is better in its own way (more readable, and resembles rendered doc more). I don't currently feel that way about the shorthand syntax. I definitely understand the point about putting users off, but a) mdformat is an opinionated formatter, not a text passthrough function, and b) users don't pay me so I don't necessarily have to care 😄. If someone were to contribute a `--keep-directive-style` flag I'd merge it.
	maxdepth: 2
	---
		using
		architecture
		other
Expand Down

26 changes: 13 additions & 13 deletions docs/using.md

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -124,19 +124,19 @@ The `smartquotes` and `replacements` components are intended to improve typograp

		`replacements` will replace particular text constructs:

	- ``(c)``, ``(C)`` → ©
	- ``(tm)``, ``(TM)`` → TM
	- ``(r)``, ``(R)`` → ®
	- ``(p)``, ``(P)`` → §
	- ``+-`` → ±
	- ``...`` → ...
	- ``?....`` → ?..
	- ``!....`` → !..
	- ``????????`` → ???
	- ``!!!!!`` → !!!
	- ``,,,`` → ,
	- ``--`` → &ndash
	- ``---`` → &mdash
	- `(c)`, `(C)` → ©
	- `(tm)`, `(TM)` → TM
	- `(r)`, `(R)` → ®
	- `(p)`, `(P)` → §
	- `+-` → ±
	- `...` → ...
	- `?....` → ?..
	- `!....` → !..
	- `????????` → ???
	- `!!!!!` → !!!
	- `,,,` → ,
	- `--` → &ndash
	- `---` → &mdash

		Both of these components require typography to be turned on, as well as the components enabled:

Expand Down

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

📚 DOCS: Format docs with mdformat-myst #156

Are you sure you want to change the base?

Uh oh!

📚 DOCS: Format docs with mdformat-myst #156

Filter by extension

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

@chrisjsewell chrisjsewell Apr 25, 2021

Choose a reason for hiding this comment

Uh oh!

@chrisjsewell chrisjsewell Apr 25, 2021

Choose a reason for hiding this comment

Uh oh!

@hukkin hukkin Apr 25, 2021 •

edited

Loading

Uh oh!

Choose a reason for hiding this comment

Uh oh!

@chrisjsewell chrisjsewell Apr 25, 2021

Choose a reason for hiding this comment

Uh oh!

@hukkin hukkin Apr 26, 2021

Choose a reason for hiding this comment

Uh oh!

📚 DOCS: Format docs with mdformat-myst #156

Are you sure you want to change the base?

Uh oh!

📚 DOCS: Format docs with mdformat-myst #156

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

@chrisjsewell chrisjsewell Apr 25, 2021

Choose a reason for hiding this comment

Uh oh!

@chrisjsewell chrisjsewell Apr 25, 2021

Choose a reason for hiding this comment

Uh oh!

@hukkin hukkin Apr 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

@chrisjsewell chrisjsewell Apr 25, 2021

Choose a reason for hiding this comment

Uh oh!

@hukkin hukkin Apr 26, 2021

Choose a reason for hiding this comment

Uh oh!

@hukkin hukkin Apr 25, 2021 •

edited

Loading