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]

我知道这篇帖子来自 2020 年，但鉴于它从未得到解答（除了说“看看其他代码”和“表格太难了”），我想我应该尽我所能提供帮助，因为我目前正在编写自己的 bbcode 插件，并且在完全没有文档的情况下挣扎。

我看了一下你的 [table] bbcode 语法，这是一个非常合理的插件，它只是做了一些包装。说真的，我认为 sam 甚至没有看你发送的链接，因为你的表格 bbcode 格式几乎就是 html 表格格式，但使用了 bbcode 标签。

这篇帖子真的帮助我解释了如何做到这一点。

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…

我现在没有时间解释如何做你想做的事情（并测试它是否真的有效），所以现在我可以告诉你 html_raw 和 html_block 令牌类型非常方便。此外，弄清楚它是否真的在工作的最好方法是，在 wrap 函数中放入 console.log()，然后在控制台中查看你实际收到的内容（并查看你正在做的事情是否有效，而不必担心 discourse 激进的清理器）。

[TheDarkWizard]

在我们用 markdown 扩展取得一些进展后，我们开始开发一个新的 bbcode 插件，但最终认为它不会像我们希望的那样奏效。我们希望在今年夏天之前完成最后 3 个左右的插件，然后尽快迁移。

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

然而，表格很可能不会有 bbcode 等效项，用户将被指示使用 markdown 版本。没有人喜欢表格。

[ego-lay_atman-bay]

这看起来确实不错。我知道你已经放弃了 bbcode 表格，但如果你愿意，我仍然可以帮助创建一个脚本来让它工作。

[TheDarkWizard]

欢迎随时查看仓库、提交 PR 或进行其他任何您想做的事情 :)！