alphagov / tech-docs-gem

Gem to distribute the tech docs project
https://tdt-documentation.london.cloudapps.digital/
MIT License
15 stars 38 forks source link

Intent to remove: indentation turning markdown into code blocks. #169

Closed NickColley closed 4 years ago

NickColley commented 4 years ago

I think we should turn off the feature to allow indented code blocks to allow for more complex readable views.

Fenced code block

` ` `javascript
function helloWorld () {
    console.log("Hello, World.")
}
helloWorld()
` ` `

Indented code block

    function helloWorld () {
       console.log("Hello, World.")
    }
    helloWorld()

When working on more complex pages it's good to be able to indent your code within conditional statements so it's readable.

    <% if condition %>
        ## Conditional section

        I'm only here some of the time.
    <% end %>

However by doing so the markdown renderer will turn code into code blocks, which means you're forced to have inconsistent indentation.

    <% if condition %>
## Conditional section

I'm only here some of the time.
    <% end %>

We use fenced codeblocks mainly for the ability to be able to set the language of the code and allow for syntax highlighting, so I think it's good to always be explicit.

We can use the disable_indented_code_blocks option for the markdown renderer to do this.

NickColley commented 4 years ago

We may revisit this, closing for now.