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.

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

Added examples on how to add and modify rules #619

Merged
merged 4 commits into from Apr 18, 2022
Merged

Added examples on how to add and modify rules #619

merged 4 commits into from Apr 18, 2022

Conversation

saenglert
Copy link
Contributor

Hello everyone,
thanks again @puzrin, for helping me out in #617 (@rl-saen is the GitHub account I use at work).

You said you don't have the time write a book about how to use markdown-it, so I thought I'd help out a little and write a guide on the problem you helped me solve. It is 75% finished, only for the last example I need a little help on how to properly create and insert a new token.

Can you please take a look at it?

docs/examples/custom_rules.md Outdated Show resolved Hide resolved
docs/examples/custom_rules.md Outdated Show resolved Hide resolved
docs/examples/custom_rules.md Outdated Show resolved Hide resolved
docs/examples/custom_rules.md Outdated Show resolved Hide resolved
docs/examples/custom_rules.md Outdated Show resolved Hide resolved
docs/examples/custom_rules.md Outdated Show resolved Hide resolved
docs/examples/custom_rules.md Outdated Show resolved Hide resolved
@rlidwka
Copy link
Member

rlidwka commented Sep 11, 2020

Can you please take a look at it?

Okay, I've taken a look at it. Please rename the file to renderer rules (see my explanation in the review above), and we can merge it hoping that it may help someone.

But honestly, I've never felt this part (renderer) needs any documentation. It's intended as a simple way for people to add custom hacks.


There is another part of markdown that needs documentation more urgently.

This:

function add_wrapper_span_plugin(md) {
  md.core.ruler.push('add_wrapper_span', function add_wrapper_span(state) {
    let inside_list = false

    for (let token of state.tokens) {
      if (token.type === 'list_item_open') inside_list = true
      if (token.type === 'list_item_close') inside_list = false

      if (inside_list && token.type === 'inline') {
        token.children.forEach(token => token.level++)
        token.children.unshift(new state.Token('wrapper_span_open', 'span', 1))
        token.children.push(new state.Token('wrapper_span_close', 'span', -1))
      }
    }
  })
}

let mit = require('markdown-it')
let md = new mit().use(add_wrapper_span_plugin)

console.log(md.render('- hello world'))
// <ul>
// <li><span>hello world</span></li>
// </ul>

It is a plugin that works before renderer. It is a way to add your example span while remaining compatible with any other plugin that potentially wants to do the same thing.

And it's better in every way except... there is no documentation how to make one, and there's no way people can find out how to write these things. :(

@saenglert
Copy link
Contributor Author

Wow, almost forgot this PR still exists!

I corrected the spelling mistakes, added some more context thanks to your explanation and fixed the last code example.

And yeah, I agree your middleware solution seems a lot more streamlined. As my focus at work has shifted quite a bit I am currently not using markdown-it anymore and even had some trouble getting the last example to work properly as I am not really used to it anymore.

So I hope someone else can step into the breach and pick this up.

@rlidwka rlidwka merged commit bab0baf into markdown-it:master Apr 18, 2022
@rlidwka
Copy link
Member

rlidwka commented Apr 18, 2022

Okay, merged. This is basic stuff, but I hope it will still be useful.

Unfortunately, we don't have time and resources to maintain such documentation. So it may get partially or fully removed if examples stops working due to breaking changes in the future.

If someone wants to expand on this or add more documentation, maybe we should start a wiki.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants