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