Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

📚 DOCS: Format docs with mdformat-myst #156

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

📚 DOCS: Format docs with mdformat-myst #156

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
05f1652
📚 DOCS: Format docs with mdformat-myst
hukkinj1 Apr 15, 2021
125aca5
DOCS: Fix list indentation
hukkinj1 Apr 15, 2021
93fe9a3
Update mdformat
hukkinj1 Apr 22, 2021
c112fcc
Merge branch 'master' into mdformat-myst
chrisjsewell Apr 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
9 changes: 8 additions & 1 deletion .pre-commit-config.yaml
View file
Open in desktop
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
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)`` → ™
- ``(r)``, ``(R)`` → ®
- ``(p)``, ``(P)`` → §
- ``+-`` → ±
- ``...`` → …
- ``?....`` → ?..
- ``!....`` → !..
- ``????????`` → ???
- ``!!!!!`` → !!!
- ``,,,`` → ,
- ``--`` → &ndash
- ``---`` → &mdash
- `(c)`, `(C)` → ©
- `(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
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
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
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
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

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

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
Member Author

@hukkin hukkin Apr 25, 2021 •
edited

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

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
Member Author

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
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)`` → ™
- ``(r)``, ``(R)`` → ®
- ``(p)``, ``(P)`` → §
- ``+-`` → ±
- ``...`` → …
- ``?....`` → ?..
- ``!....`` → !..
- ``????????`` → ???
- ``!!!!!`` → !!!
- ``,,,`` → ,
- ``--`` → &ndash
- ``---`` → &mdash
- `(c)`, `(C)` → ©
- `(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