Documentation of Blackfriday extensions

1

Hello,

Can you please add documentation about Blackfriday extensions:

  • Case-sensitive extension names to be used in the extensions and extensionsmask list variables under blackfriday table.
  • Short description for each extension, just as you have for each Blackfriday option.
  • Default enabled/disabled state of each extension in Hugo.

Thanks.

2

Is this what you’re looking for?

3

I have already seen that. That paging is lacking exactly the detailed information about the extensions. Scroll to the extensions section on that page. In addition to the Blackfriday options (those are documented), there are about a dozen extensions, which are not documented.

User does not know which extensions are enabled by default, what case-sensitive name to use to enable/disable.

4

I am working on an Emacs Org-mode package and in the process I needed to do some digging about Blackfriday extensions as the official docs do not have any info.

I dug through the following sources to finally get this.

  • Figuring out the case-sensitive names used by Hugo and which extensions are enabled by default – Hugo content.go.
  • Getting decriptions for those extensions, part 1 – blackfriday README
  • But that was incomplete, so getting decriptions for those extensions, part 2 – blackfriday markdown.go
  • But even that is incomplete. So if you look at the above link to my ox-hugo.el, you will find «Needs more information», which I still need to completely understand what that extension does.
5

These are the Blackfriday extensions supported by Hugo:

These should be listed in the Hugo documentation. If not, contributions are welcomed. That includes you, @kaushalmodi.

But it should, ideally, link to documentation in the Blackfriday library.

6

@kaushalmodi As an FYI, the config options are mentioned in more than one place in the documentation, so I created a simple readfile so we weren’t updating in multiple places. This was before .GetPage.

You can see the file in question here:

7

You probably missed my post above bep’s.

I am already aware of the blackfriday options. There’s a difference between blackfriday options and blackfriday extensions. The extensions need to be documented.

Please look at this example .md file for Hugo.

From that:

+++
title = "Enabling/Disabling extensions (TOML)"
date = 2017-08-02
tags = ["blackfriday", "toml"]
draft = false
[blackfriday]
  extensionsmask = ["fencedCode", "strikethrough"]
  extensions = ["tabSizeEight", "hardLineBreak"]
  plainIDAnchors = false
  hrefTargetBlank = true
  smartDashes = false
  fractions = false
  angledQuotes = true
+++

…, I am talking about the lack of documentation of the below part:

  extensionsmask = ["fencedCode", "strikethrough"]
  extensions = ["tabSizeEight", "hardLineBreak"]
1 Like
8

No, I didn’t miss it. If I don’t read a thread, I usually start with “Sorry I’m too late to this thread to read everything above, but…”

I’m sending you in the right direction in the source per @bep 's suggestion to make a PR and make changes to documentation if we are missing something. I wanted to save you the step of wondering where this documentation/content lives rather than going directly to a different markdown file. HTH

9

Ah OK.

I already knew about that (link). I just felt that I don’t have enough authority to update the documentation myself as I don’t know Go. But in any case, I’ll go ahead and work on a PR. As you seen in that link, if you search for “Needs more” in your browser, there are few places I don’t know what to document as I would need to reverse engineer the blackfriday extension code to figure that out.

10

@rdwatters I thought, docs was a submodule in the hugo… it still isn’t?

How is https://github.com/gohugoio/hugoDocs/blob/master/content/readfiles/bfconfig.md copied to https://github.com/gohugoio/hugo/blob/master/docs/content/readfiles/bfconfig.md ?

11

Well, the hugo repo version has the new option smartypantsQuotesNBSP documented while the hugoDocs repo version does not. Should I still provide hugoDocs PR?

Or is hugoDocs only for released hugo versions, while the docs/ dir in hugo updates to the master?

12

“That (link)” isn’t the link I gave you. We moved to a GitHub org a couple months ago and broke out the docs and theme as separate repos. But yes, the docs are still part of the download of the single binary.

This was another reason why I was hoping to save you some time by pointing you directly to that quasi-data/readfile for all things BF in the docs if you wanted to kindly help us improve the documentation :wink:

13

Thanks. I realized that as you see in the later comments… but am confused why the hugo repo version is newer and not the hugoDocs version.

14

It is called versioning.

  • hugo/docs follows the current Hugo code base (i.e. the master branch) and will contain features not yet released, i.e. smartypantsQuotesNBSP
  • hugoDocs master is what is deployed to gohugo.io and, should if we do the job well, represent the latest Hugo binary version.

Note that the hugoDocs repo is moving fast and there is no auto-merge between the two, so they will not be in sync at all times.

2 Likes
15

PR submitted.

1 Like
16

A post was split to a new topic: Blackfriday extensionmask content heading ids