Markdown Extensions for BBCode

[Ghan]

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:

Developer's guide to Markdown extensions

Discourse uses a Markdown engine called Markdown-it. Here are some dev notes that will help you either fix bugs in core or create your new plugins. The Basics Discourse only contains a few helpers on top of the engine, so the vast majority of learning that needs to be done, is understanding Markdown It. The docs directory contains the current documentation. I strongly recommend reading: The architecture document to understand at a top level how the engine works. Development for basic…

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?

@sam

In this case we are replacing an entire [code]code block[code] with a single code_inline token.

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!

[codinghorror (Jeff Atwood)]

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

[Ghan]

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.

[sam (Sam Saffron)]

@Ghan

First, I’m trying to build a [table] bbcode to start out.

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.

[TheDarkWizard]

@sam

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

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.

[ego-lay_atman-bay]

Je sais que ce post date de 2020, mais comme il n’a jamais reçu de réponse (à part dire « regardez d’autres codes » et « les tableaux sont trop difficiles »), j’ai pensé apporter ma contribution et expliquer comment je peux aider, car j’écris actuellement mon propre plugin bbcode et j’ai dû me débrouiller sans aucune documentation.

J’ai examiné votre syntaxe bbcode [table] et c’est un plugin tout à fait raisonnable à créer, ce n’est qu’un enrobage. Sérieusement, je ne pense pas que Sam ait même regardé le lien que vous avez envoyé, car votre format de tableau bbcode est à peu près le même que le format de tableau HTML, mais avec des balises bbcode.

Ce post a vraiment aidé à expliquer un peu comment faire cela.

Developer's guide to Markdown extensions

Discourse uses a Markdown engine called Markdown-it. Here are some dev notes that will help you either fix bugs in core or create your new plugins. The Basics Discourse only contains a few helpers on top of the engine, so the vast majority of learning that needs to be done, is understanding Markdown It. The docs directory contains the current documentation. I strongly recommend reading: The architecture document to understand at a top level how the engine works. Development for basic d…

Je n’ai pas le temps en ce moment d’expliquer comment faire ce que vous voulez faire (et de tester pour voir si cela fonctionne réellement), donc pour l’instant, je peux vous dire que les types de jetons html_raw et html_block sont très utiles. De plus, la meilleure façon de savoir si cela fonctionne réellement est de mettre console.log() dans la fonction wrap, puis de voir ce que vous recevez réellement dans la console (et de voir si ce que vous faites fonctionne, sans avoir à vous soucier du nettoyeur agressif de discourse).

[TheDarkWizard]

Nous avons commencé à travailler sur un nouveau plugin bbcode après avoir fait des progrès avec les extensions markdown, mais avons finalement décidé que cela ne fonctionnerait pas aussi bien que nous l’espérions. Nous espérons avoir les 3 derniers environ d’ici cet été, puis migrer peu de temps après.

GitHub - RpNation/bbcode: RpNation's Official BBCode Implementation for...

Cependant, les tableaux n’auront très probablement pas d’équivalent bbcode et les utilisateurs seront invités à utiliser la version markdown. Personne n’aime les tableaux.

[ego-lay_atman-bay]

Ça a l’air vraiment bien. Je sais que vous avez abandonné les tableaux bbcode, mais si vous voulez, je peux toujours vous aider à créer un script pour que cela fonctionne.

[TheDarkWizard]

Vous êtes les bienvenus pour aller voir le dépôt, faire des PRs ou tout ce que vous voulez !