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]

Sei que esta postagem é de 2020, mas como ela nunca foi respondida (além de apenas dizer “olhe outro código” e “tabelas são muito difíceis”), pensei em contribuir e explicar como posso ajudar, já que estou escrevendo meu próprio plugin bbcode e tive que lutar sem nenhuma documentação.

Dei uma olhada na sua sintaxe de bbcode [table], e é um plugin perfeitamente razoável de se fazer, é apenas um encapsulamento. Sério, acho que o Sam nem olhou o link que você enviou, porque o formato do seu bbcode de tabela é praticamente o formato de tabela HTML, mas com tags bbcode.

Esta postagem realmente ajudou a explicar um pouco sobre como fazer isso.

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…

Não tenho tempo agora para explicar como fazer o que você quer fazer (e testar para ver se realmente funciona), então, por enquanto, posso dizer que os tipos de token html_raw e html_block são bem úteis. Além disso, a melhor maneira de descobrir se está realmente funcionando é colocar console.log() na função wrap e, em seguida, ver o que você está realmente recebendo de volta no console (e ver se o que você está fazendo está funcionando, sem ter que se preocupar com o sanitizador agressivo do Discourse).

[TheDarkWizard]

Começamos a trabalhar em um novo plugin bbcode depois de fazermos algum progresso com as extensões markdown, mas, no final, decidimos que não funcionaria tão bem quanto esperávamos. Esperamos ter os últimos 3 mais ou menos até este verão e, em seguida, migrar logo depois disso.

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

No entanto, as tabelas provavelmente não terão um equivalente em bbcode e os usuários serão instruídos a usar a versão markdown. Ninguém gosta de tabelas.

[ego-lay_atman-bay]

Isso parece muito bom. Sei que você desistiu das tabelas bbcode, mas se quiser, ainda posso ajudar a criar um script para fazê-lo funcionar.

[TheDarkWizard]

Sinta-se à vontade para olhar o repositório, fazer PRs ou o que mais quiser :)!