Skip to content

Commit

Permalink
Refactor docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Jan 14, 2025
1 parent 38632d3 commit e0d94a8
Show file tree
Hide file tree
Showing 5 changed files with 110 additions and 86 deletions.
12 changes: 11 additions & 1 deletion .remarkrc.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,15 @@ import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import remarkToc from 'remark-toc'
import remarkValidateLinks from 'remark-validate-links'
import remarkLintListItemIndent from 'remark-lint-list-item-indent'
import remarkLintCorrectMediaSyntax from 'remark-lint-correct-media-syntax'
import remarkLintDefinitionSort from 'remark-lint-definition-sort'
import remarkLintFencedCodeFlag, {
checkGithubLinguistFlag
} from 'remark-lint-fenced-code-flag'
import remarkLintHardBreakSpaces from 'remark-lint-hard-break-spaces'
import remarkLintListItemIndent from 'remark-lint-list-item-indent'
import remarkLintMediaStyle from 'remark-lint-media-style'
import remarkLintNoHiddenTableCell from 'remark-lint-no-hidden-table-cell'
import listOfPlugins from './script/plugin/list-of-plugins.js'
import listOfPresets from './script/plugin/list-of-presets.js'

Expand All @@ -19,8 +24,13 @@ export default {
remarkGithub,
remarkPresetLintConsistent,
remarkPresetLintRecommended,
remarkLintCorrectMediaSyntax,
remarkLintDefinitionSort,
[remarkLintFencedCodeFlag, checkGithubLinguistFlag],
[remarkLintHardBreakSpaces, {allowSpaces: false}],
[remarkLintListItemIndent, 'one'],
[remarkLintMediaStyle, 'reference-reuse'],
remarkLintNoHiddenTableCell,
[remarkToc, {maxDepth: 3}],
remarkValidateLinks,
listOfPlugins,
Expand Down
47 changes: 25 additions & 22 deletions doc/create-a-custom-rule.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ Now we can start installing our dependencies:
npm install remark-lint remark-cli
```

* [`remark-lint`][remark-lint]
* [`remark-lint`][github-remark-lint]
— core lint plugin
* [`remark-cli`][remark-cli]
* [`remark-cli`][github-remark-cli]
— command line interface

We will also use some utilities:
Expand All @@ -50,7 +50,8 @@ These will help us creating and managing our custom rules.
With everything installed, we can now create a `.remarkrc.js` that will contain
the plugins we’ll use.

For more info on configuration, see [Examples in `remark-lint`][examples].
For more info on configuration, see
[Examples in `remark-lint`][github-remark-lint-examples].

```sh
touch .remarkrc.js
Expand Down Expand Up @@ -183,20 +184,22 @@ Your rule function will receive three arguments:
function rule(tree, file, options) {}
```

* `tree` (*required*): [mdast][]
* `file` (*required*): [virtual file][vfile]
* `tree` (*required*): [mdast][github-mdast]
* `file` (*required*): [virtual file][github-vfile]
* `options` (*optional*): additional info passed to the rule by users

## Rule implementation

Because we will be inspecting [mdast][], which is a markdown abstract syntax
tree built upon [unist][], we can take advantage of the many existing
[unist utilities][unist-util] to inspect our tree’s nodes.
Because we will be inspecting [mdast][github-mdast],
which is a markdown abstract syntax tree built upon [unist][github-unist],
we can take advantage of the many existing
[unist utilities][github-unist-utilities] to inspect our tree’s nodes.

For this example, we will use [`unist-util-visit`][unist-util-visit] to
recursively inspect all the image nodes, and
[`unist-util-generated`][unist-util-generated] to ensure we are not inspecting
nodes that we have generated ourselves and do not belong to the `doc.md`.
For this example, we will use [`unist-util-visit`][github-unist-util-visit]
to recursively inspect all the image nodes, and
[`unist-util-generated`][github-unist-util-generated] to ensure we are not
inspecting nodes that we have generated ourselves and do not belong to the
`doc.md`.

```js
/**
Expand Down Expand Up @@ -269,22 +272,22 @@ If you run `npm run lint`, you should see the following message in the terminal:
**Congratulations!
The rule works!**

[tutorial]: https://dev.to/floroz/how-to-create-a-custom-lint-rule-for-markdown-and-mdx-using-remark-and-eslint-2jim
[github-mdast]: https://github.com/syntax-tree/mdast

[remark-lint]: https://github.com/remarkjs/remark-lint
[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli

[remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
[github-remark-lint]: https://github.com/remarkjs/remark-lint

[examples]: https://github.com/remarkjs/remark-lint#examples
[github-remark-lint-examples]: https://github.com/remarkjs/remark-lint#examples

[mdast]: https://github.com/syntax-tree/mdast
[github-unist]: https://github.com/syntax-tree/unist

[vfile]: https://github.com/vfile/vfile
[github-unist-util-generated]: https://github.com/syntax-tree/unist-util-generated

[unist]: https://github.com/syntax-tree/unist
[github-unist-util-visit]: https://github.com/syntax-tree/unist-util-visit

[unist-util]: https://github.com/syntax-tree/unist#utilities
[github-unist-utilities]: https://github.com/syntax-tree/unist#utilities

[unist-util-visit]: https://github.com/syntax-tree/unist-util-visit
[github-vfile]: https://github.com/vfile/vfile

[unist-util-generated]: https://github.com/syntax-tree/unist-util-generated
[tutorial]: https://dev.to/floroz/how-to-create-a-custom-lint-rule-for-markdown-and-mdx-using-remark-and-eslint-2jim
1 change: 1 addition & 0 deletions packages/remark-preset-lint-consistent/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ import remarkLintTableCellPadding from 'remark-lint-table-cell-padding'
// To do: next major:
// - add `remark-lint-mdx-jsx-quote-style`.
// - add `remark-lint-mdx-jsx-unique-attribute-name`.
// - add `remark-lint-media-style`

/** @type {Preset} */
const remarkPresetLintConsistent = {
Expand Down
2 changes: 1 addition & 1 deletion packages/remark-preset-lint-recommended/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ import remarkLintOrderedListMarkerStyle from 'remark-lint-ordered-list-marker-st

// To do: next major:
// * add `remark-lint-fenced-code-flag` w/ GH check
// * add `remark-lint-correct-link-syntax`
// * add `remark-lint-correct-media-syntax`
// * add `remark-lint-no-hidden-table-cell`

/** @type {Preset} */
Expand Down
134 changes: 72 additions & 62 deletions readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
# ![remark-lint][logo]
# ![remark-lint][file-logo]

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Chat][chat-badge]][chat]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
[![Sponsors][badge-sponsors-image]][badge-collective-url]
[![Backers][badge-backers-image]][badge-collective-url]
[![Chat][badge-chat-image]][badge-chat-url]

**[remark][]** plugins to check (lint) markdown code style.
**[remark][github-remark]** plugins to check (lint) markdown code style.

## Contents

Expand Down Expand Up @@ -62,7 +63,8 @@ This GitHub repository is a monorepo that contains ±70 plugins (each a rule tha
checks one specific thing) and 3 presets (combinations of rules configured to
check for certain styles).

These packages are build on [unified][] ([remark][]).
These packages are build on [unified][github-unified]
([remark][github-remark]).
**unified** is a project that inspects and transforms content with abstract
syntax trees (ASTs).
**remark** adds support for markdown to unified.
Expand All @@ -76,7 +78,8 @@ documentation in markdown and you want to ensure that the markdown is
consistent, free of bugs, and works well across different markdown parsers.

These packages are quite good at checking markdown.
They especially shine when combined with other [remark plugins][remark-plugin]
They especially shine when combined with other
[remark plugins][github-remark-plugin]
and at letting you make your own rules.

## Presets
Expand Down Expand Up @@ -254,7 +257,7 @@ The following rules are maintained by the community:
— wrapper for `write-good`

For help creating your own rule, it’s suggested to look at existing rules and to
[follow this tutorial][tutorial].
[follow this tutorial][file-create-a-custom-rule].

## Configure

Expand Down Expand Up @@ -299,7 +302,7 @@ remark()
.use(remarkLintMaximumLineLength, [1, 72])
```

See [`use()` in `unified`s readme][unified-use] for more info on how to use
See [`use()` in `unified`s readme][github-unified-use] for more info on how to use
plugins.

> 🧑‍🏫 **Info**: messages in `remark-lint` are warnings instead of errors.
Expand Down Expand Up @@ -360,9 +363,9 @@ You can ignore a message in the next block with `<!--lint ignore-->`:
> 👉 **Note**: you’ll typically need blank lines between HTML comments and other
> constructs.
> More info is available at the package that handles comments,
> [`remark-message-control`][remark-message-control].
> [`remark-message-control`][github-remark-message-control].
> 💡 **Tip**: MDX comments are supported when [`remark-mdx`][remark-mdx] is
> 💡 **Tip**: MDX comments are supported when [`remark-mdx`][mdx-remark-mdx] is
> used:
>
> ```mdx
Expand Down Expand Up @@ -421,7 +424,8 @@ Running that with `node example.js` yields:
### Example: check and format markdown on the API
remark lint rules *check* markdown.
[`remark-stringify`][remark-stringify] (used in remark) *formats* markdown.
[`remark-stringify`][github-remark-stringify]
(used in remark) *formats* markdown.
When you configure lint rules and use remark to format markdown, you must
manually synchronize their configuration:
Expand Down Expand Up @@ -462,7 +466,7 @@ If that output was given the the processor, the lint rules would be satisfied.
### Example: check markdown on the CLI
This example checks markdown with [`remark-cli`][remark-cli].
This example checks markdown with [`remark-cli`][github-remark-cli].
It assumes you’re in a Node.js package.
First install dependencies:
Expand Down Expand Up @@ -563,7 +567,7 @@ Update `remarkConfig`:
```
This now includes `settings`, which configures
[`remark-stringify`][remark-stringify], and explicitly prefers asterisks
[`remark-stringify`][github-remark-stringify], and explicitly prefers asterisks
for emphasis and strong.
Install the new dependencies:
Expand Down Expand Up @@ -599,15 +603,16 @@ npm run format
## Syntax
Markdown is parsed by [`remark-parse`][remark-parse] (included in `remark`)
Markdown is parsed by [`remark-parse`][github-remark-parse]
(included in `remark`)
according to CommonMark.
You can combine it with other plugins to add syntax extensions.
Notable examples that deeply integrate with it are
[`remark-gfm`][remark-gfm],
[`remark-mdx`][remark-mdx],
[`remark-frontmatter`][remark-frontmatter],
[`remark-math`][remark-math], and
[`remark-directive`][remark-directive].
[`remark-gfm`][github-remark-gfm],
[`remark-mdx`][mdx-remark-mdx],
[`remark-frontmatter`][github-remark-frontmatter],
[`remark-math`][github-remark-math], and
[`remark-directive`][github-remark-directive].
## Compatibility
Expand All @@ -622,88 +627,93 @@ with Node.js 16.
## Security
Use of `remark-lint` does not change the tree so there are no openings for
[cross-site scripting (XSS)][xss] attacks.
[cross-site scripting (XSS)][wikipedia-xss] attacks.
Messages from linting rules may be hidden from user content though, causing
builds to fail or pass.
## Contribute
See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
to get started.
See [`support.md`][support] for ways to get help.
See [`contributing.md`][health-contributing]
in [`remarkjs/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.
This project has a [code of conduct][coc].
This project has a [code of conduct][health-coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.
## License
[MIT][license] © [Titus Wormer][author]
[MIT][file-license] © [Titus Wormer][wooorm]
<!-- Definitions -->
[build-badge]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
[badge-backers-image]: https://opencollective.com/unified/backers/badge.svg
[build]: https://github.com/remarkjs/remark-lint/actions
[badge-build-image]: https://github.com/remarkjs/remark-lint/actions/workflows/main.yml/badge.svg
[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
[coverage]: https://codecov.io/github/remarkjs/remark-lint
[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
[downloads-badge]: https://img.shields.io/npm/dm/remark-lint.svg
[badge-chat-url]: https://github.com/remarkjs/remark/discussions
[downloads]: https://www.npmjs.com/package/remark-lint
[badge-collective-url]: https://opencollective.com/unified
[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
[chat]: https://github.com/remarkjs/remark/discussions
[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint.svg
[backers-badge]: https://opencollective.com/unified/backers/badge.svg
[badge-downloads-url]: https://www.npmjs.com/package/remark-lint
[collective]: https://opencollective.com/unified
[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint
[health]: https://github.com/remarkjs/.github
[badge-size-url]: https://bundlejs.com/?q=remark-lint
[badge-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
[file-create-a-custom-rule]: doc/create-a-custom-rule.md
[support]: https://github.com/remarkjs/.github/blob/main/support.md
[file-license]: license
[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
[file-logo]: https://raw.githubusercontent.com/remarkjs/remark-lint/014fca7/logo.svg?sanitize=true
[license]: license
[github-remark]: https://github.com/remarkjs/remark
[author]: https://wooorm.com
[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
[unified]: https://github.com/unifiedjs/unified
[github-remark-directive]: https://github.com/remarkjs/remark-directive
[unified-use]: https://github.com/unifiedjs/unified#processoruseplugin-options
[github-remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
[remark]: https://github.com/remarkjs/remark
[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
[remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
[github-remark-math]: https://github.com/remarkjs/remark-math
[remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
[github-remark-message-control]: https://github.com/remarkjs/remark-message-control
[remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
[remark-plugin]: https://github.com/remarkjs/remark#plugins
[github-remark-plugin]: https://github.com/remarkjs/remark#plugins
[remark-message-control]: https://github.com/remarkjs/remark-message-control
[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
[remark-gfm]: https://github.com/remarkjs/remark-gfm
[github-unified]: https://github.com/unifiedjs/unified
[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
[github-unified-use]: https://github.com/unifiedjs/unified#processoruseplugin-options
[health]: https://github.com/remarkjs/.github
[remark-math]: https://github.com/remarkjs/remark-math
[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
[remark-directive]: https://github.com/remarkjs/remark-directive
[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
[remark-mdx]: https://mdxjs.com/packages/remark-mdx/
[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
[logo]: https://raw.githubusercontent.com/remarkjs/remark-lint/014fca7/logo.svg?sanitize=true
[mdx-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[tutorial]: doc/create-a-custom-rule.md
[wooorm]: https://wooorm.com

0 comments on commit e0d94a8

Please sign in to comment.