Markdown Extensions for BBCode

Dev
1

I am trying to learn how to write markdown rules to implement new bbcode functionality using this guide, however I’m having a really hard time following what is going on as there is so much that is unexplained:

I also checked out the markdown-it documentation, but it is very sparse and seems to mostly be a very high-level overview of the functionality of the system. Some specific question I have:

  • The guide has this line: // standard markdown it inline extension goes here.
    What is the standard inline extension? Is this where you define the rules that are pushed to the ruler? Why does it return false?

  • What are the token types? I see examples like 'link_open' and 'html_inline' - where do these come from? Is there a static list somewhere of what is available? Can I add new ones? How does the parser know what to do with these?

How does this work? How does the parser know what 'code_inline' does? What does the state.push() function do and how is it intended to be used?

I feel like I’m close to “getting it” but I think I’m missing some concepts. I’ve written the most basic of rules and it appears to be working - I just need a better understanding to move forward. Any help would be appreciated!

2

Why aren’t you looking at the existing official BBCode plugin that adds [color] support, etc?

2 Likes
3

I have been going over and over the official BBCode plugin at https://github.com/discourse/discourse-bbcode but so far I’m not making much progress and I still don’t have a good understanding of the inner workings.

First, I’m trying to build a [table] bbcode to start out. I realize that markdown has support for tables already, but (assuming I can build support for our other bbcodes) we’ll be migrating around 20 million posts to Discourse, so I want to have backwards compatibility working properly for existing bbcodes, and the way that the pipe character is used in markdown makes raking the posts to convert tables basically impossible.

My table tag I’ve built so far keeps getting deleted. It’s there in the post, but continues to (I assume) be removed by the scrubber. This is what I have at the moment:

md.block.bbcode.ruler.push("table", {
    tag: "table",
    wrap: function(token, tagInfo) {
      token.attrs = [['class', "bbcode-table table-style-" + tagInfo.attrs['_default']]];
      return true;
    }
  });

helper.whiteList([
    "table.bbcode-table",
    "table.table-style-*"

I’ve tried other formatting of the whitelist and the wrap function based on other examples I’ve seen, but so far nothing is working, so I assume there’s something fundamental about how the system works that I don’t understand. I’m trying to get a better understanding so I’ll be able to more consistently get things working going forward.

4

Table is probably the most complicated thing you could build, highly recommend you start with far simpler things.

In fact I would advice against having bbcode table support even if you could write it.

2 Likes
5

We have a simple list of bbcodes that we are trying to support like @Ghan explained because we are a 20 million + board. We are by no means a small community and this was not an easy decision that we came to, but we have determined that Discourse is the best software for us moving forward. We’ve gotten the import ironed out, the only thing that is stopping us from migrating is just figuring out this last step. Now I can be convinced to drop tables since we want to drop any BBCode that Discourse or Markdown fully supports. However, Tables was one that couldn’t just be easily rebaked into the markdown version because replacing table td tr and so forth into the correct Markdown Syntax is not easy or rather nigh impossible as far as I can tell. So dropping it is fine, even if it can’t be rebaked easily but just learning how to do it, will most likely help us figure out everything else.

We were able to drop [h1] as an example because that one is indeed simple to alter since all the H tags just need to become the equivalent number of #.

We have an entire list at: Tutorial - RpNation - BBcode Guide | RpNation and a few more besides the ones in this thread, have already been dropped because they were super simple to find/replace into the markdown equivalent.

4 Likes
6

I know this post is from 2020, but seeing as how it was never answered (other than just saying “go look at other code” and “tables are too hard”) I thought I’d chip in and explain help how I can, since I’m currently writing my own bbcode plugin, and had to struggle with absolutely no documentation.

I took a look at your [table] bbcode syntax, and it’s a perfectly reasonable plugin to make, it’s just some wrapping. Seriously, I don’t think sam even looked at the link you sent, because your table bbcode format, is pretty much just the html table format, but with bbcode tags.

This post really helped explain a bit about how to do this.

I don’t have time right now to explain how to do what you want to do (and test it to see if it actually works), so right now I can tell you that the html_raw and html_block token types are pretty handy. Also, the best way to figure out if it’s actually working, is by putting in console.log() in the wrap function, and then see what you’re actually getting back in the console (and see if what you’re doing is working, without having to worry about discourse’s aggressive sanitizer).

1 Like
7

We started working on a new bbcode plugin after we made some progress with markdown extensions but ultimately decided it wasn’t going to work as well as we had hoped. We hope to have the last 3ish down by this summer and then migrate shortly after that.

Tables however will most likely not get a bbcode equivalent and users will be instructed to use the markdown version. No one likes tables.

8

That looks really good. I know you gave up on the bbcode tables, but if you want, I can still help create a script to get it to work.

1 Like
9

You are welcome to go look at the repo, make PRs or what ever else you want :)!

2 Likes