Better indentation support

[LinusU]

I'm having some trouble with my code blocks. I don't want to indent my headers and bodies with 12 spaces since I think it looks ridiculous. Instead I'm trying to use fenced code blocks, but for some reason it dosen't seem to work.

I have the following markdown:

+ Request
  + Headers
    ```
    X-Name: Linus
    ```

It seems like the parser thinks that "```" is the name of the header, I have the following errors:

>> headers is expected to be a pre-formatted code block, separate it by a newline and indent every of its line by 12 spaces or 3 tabs (warning code 10)
>> missing colon after header name (warning code 13)
>> HTTP header has no value (warning code 13)
>> missing colon after header name (warning code 13)
>> duplicate definition of '```' header (warning code 13)
>> HTTP header has no value (warning code 13)

Am I missing something obvious?

Here is the specification saying it should work

[zdne]

@LinusU I believe there has to be an additional new line after Headers – see ho the example you have posted is rendered (incorrectly) by GitHub:

• Request
  • Headers X-Name: Linus

[LinusU]

With blank line:

+ Request
  + Headers

    ```
    X-Name: Linus
    ```

>> no headers specified (warning code 3)
>> ignoring unrecognized block (warning code 5)

[pksunkara]

@LinusU Can you try the following:

+ Request

    + Headers

        ```
        X-Name: Linus
        ```

[zdne]

yup, @pksunkara is right please use full indentation (4 spaces per a tab)

[LinusU]

Tried it and it works, but I really want to use 2 spaces for indentation.

There is no mentioning in API Blueprint Specification.md that you need to use 4 spaces or tab, and that is not a requirement in Markdown itself.

The only time you are required to use 4 spaces or 1 tab is when you are using the classic code blocks.

That is why the following markdown is perfectly valid and renders correctly.

- Item 1
  - Nested item 1
  - Nested item 2
- Item 2

[zdne]

@LinusU It is hard to argue about Markdown since there is no specification really. Original Gruber' version says:

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

and

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab

and finally

To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab.

So I bet 4 spaces is a safe bet in any Markdown flavor.

The bottom line is we are using old (deprecated) GitHub parser for processing Markdown and this is maybe the reason why the behavior diverged.

I wouldn't mind supporting two spaces but for that we would need to migrate to Hoedown or CommonMark parser (which is the plan but no ETA just yet).

TL;DR: 4 spaces is current's parser limitation :(

[LinusU]

Cool, I've updated the title of the issue. Would be cool to work on if I get some free time :)

[zdne]

@LinusU Any help is highly appreciated. What is basically needed is to replace our fork of Sundown with either Hoedown or CommonMark (to be decided). This should happen underneath the Markdown Parser and (hypothetically) no changes should be propagated outside of it...

[Californian]

Hey I was just wondering if there's been any progress on this (in particular, the parser implementation), as I can't find anything in the current issues about it.

[pksunkara]

@Californian Unfortunately, there is no update yet.

[ivan-novakov]

+1