Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Markdown inside <summary> and <details> not being processed #155

Closed
cheloizaguirre opened this issue Aug 8, 2014 · 20 comments
Closed

Markdown inside <summary> and <details> not being processed #155

cheloizaguirre opened this issue Aug 8, 2014 · 20 comments
Assignees
Labels

Comments

@cheloizaguirre
Copy link

I'm trying to use the

and

HTML tags, but any markdown inside of them that I used is ignored. Here's a sample of what I'm trying to do:

<details>
<summary>
## My test!
</summary>

* Elem1
* Elem 2
</details>

The output of that ends up being:

"<summary>\n\n## My test!\n\n</summary>\n<details>\n\n* Elem1\n* Elem 2\n</details>\n"

I've tried using the parse_block_html option and adding markdown="1" or markdown="span" to the HTML tags, but the text inside there just gets ignored.
I looked in https://github.com/gettalong/kramdown/blob/master/lib/kramdown/parser/html.rb#L57 and it seems like

should be working as expected, though

is not there, so it might be getting ignored alltogether.

I'm totally willing to look into it myself if you can point me in the direction of a good place to start. Thanks!

@gettalong gettalong self-assigned this Aug 9, 2014
@gettalong
Copy link
Owner

The HTML elements "details" and "summary" are part of HTML5 which kramdown only supports partially. I have looked at the spec and a fully correct implementation is not possible for "summary" since it supports two different content models.

This will be fixed in the next version so that both elements are recognized as having a block content model.

@gettalong
Copy link
Owner

@cheloizaguirre Please keep in mind that you will still have (i.e. after fixing this in kramdown) to use the parse_block_html option or that you need to a "markdown" attribute to the <summary> and <details> elements!

gettalong added a commit that referenced this issue Sep 9, 2014
…k content model (fixes #155)

Note that the <summary> element was using the span content model
prior to this change but the block content model is better
suited (both are allowed by the HTML5 spec).
@eneko
Copy link

eneko commented Oct 25, 2017

Hello there. Seems like it's been a while since this issue was closed. It is not clear to me, however, if Kramdown supports Markdown inside <details> for collapsible blocks.

While testing this last night, I found GitHub rendered the markdown inside properly when browsing the repo in GitHub.com, but it renders as plain test when browsing the same file on GitHub Pages.

Browsing at GitHub.com:
screenshot 2017-10-25 08 40 09

Browsing on rendered GitHub Pages:
screenshot 2017-10-25 08 40 17

If Kramdown supports Markdown inside <details>, what do I need to do for it to render properly?

@gettalong
Copy link
Owner

@eneko Just so that you know pictures are quite worthless when it comes to determining problems. Better show the input, the false output and the expected output as text.

As for your question: As written in #155 (comment) you need to enable the 'parse_block_html' option.

@eneko
Copy link

eneko commented Oct 25, 2017

Thanks! Yeah, I thought of pasting some code examples, but too much escaping to show the issue. Took the lazy path :)

Thanks, if I understand it properly, the _config.yml should look something like this, correct?

markdown: kramdown
kramdown:
  parse_block_html: true

I assume there is no other way to get this working on GitHub pages that do not have a config file, correct?

@gettalong
Copy link
Owner

For Jekyll related questions please ask on some Jekyll forum or something similar since I don't use Jekyll as my static website generator.

@eneko
Copy link

eneko commented Oct 26, 2017

@gettalong sorry to bother you again. Do you have any examples of this feature working with Kramdown, whether is with Jekyll or not? I am failing to get it to work, not sure what I'm missing.

@gettalong
Copy link
Owner

@eneko You can always use the kramdown binary to check whether the problem lies with kramdown or the tool that uses kramdown, like this:

$ echo -e "<details>\n# Header\n\nPara*graph*\n\n> quote\n</details>" | kramdown --parse-block-html
<details>
  <h1 id="header">Header</h1>

  <p>Para<em>graph</em></p>

  <blockquote>
    <p>quote</p>
  </blockquote>
</details>

As you can see the kramdown markup is correctly processed within the <details> tag. Also have a look at https://kramdown.gettalong.org/syntax.html#html-blocks

@eneko
Copy link

eneko commented Oct 26, 2017

Ok, I think I found the problem, thanks for the command line example.

The HTML <details> tag is usually paired with an embedded <summary> tag.

Looks like if a <summary> tag is present when running Kramdown with --parse-block-html, both <summary> and <details> tags are mistakenly escaped.

$ echo -e "<details><summary>Collapsed Block</summary>\n\n## Header\n</details>" | kramdown --parse-block-html
<details>
  <summary>
    <p>Collapsed Block&lt;/summary&gt;</p>

    <h2 id="header">Header</h2>
    <p>&lt;/details&gt;</p>
  </summary>
</details>
Warning: Found no end tag for 'summary' (line 1) - auto-closing it
Warning: Found no end tag for 'details' (line 1) - auto-closing it
Warning: Found invalidly used HTML closing tag for 'summary' on line 1
Warning: Found invalidly used HTML closing tag for 'details' on line 4

The nested <summary> tag is triggering the escaping issue, maybe because it is also identified as a block tag.

Nested <details> blocks, on the other hand, work as expected:

$ echo -e "<details>\nStart.\n<details>\nNested *details*.\n</details>\nEnd.\n</details>" | kramdown --parse-block-html
<details>
  <p>Start.</p>
  <details>
    <p>Nested <em>details</em>.</p>
  </details>
  <p>End.</p>
</details>

@eneko
Copy link

eneko commented Oct 26, 2017

@gettalong, let me know if you would like me to open a new issue, if that makes things easier.

@gettalong
Copy link
Owner

As stated in the syntax documentation, the closing tag for an HTML tag must start on a new line if the contents is parsed as block elements:

$ echo -e "<details><summary>Collapsed Block\n</summary>\n\n## Header\n</details>" | kramdown --parse-block-html
<details>
  <summary>
    <p>Collapsed Block</p>
  </summary>

  <h2 id="header">Header</h2>
</details>

@eneko
Copy link

eneko commented Oct 26, 2017

Ok, thanks. That is pretty close to the desired output. Is there any way to prevent the <p> tag from being added inside the summary? By doing so, it renders the summary text on the next line than the details caret, instead of next to it.

@eneko
Copy link

eneko commented Oct 26, 2017

Maybe summary shouldn't be treated as a block text, since it should be next to the expand/collapse caret "▶︎".

@gettalong
Copy link
Owner

How elements get rendered depends on the CSS; therefore kramdown can do nothing in this regard.

If you don't want to parse the contents of an HTML tag as block elements, you should use the 'parse_block_html' option. Alternatively, you can specify markdown="span":

$ echo -e "<details><summary markdown='span'>Collapsed Block\n</summary>\n\n## Header\n</details>" | kramdown --parse-block-html
<details>
  <summary>Collapsed Block
</summary>

  <h2 id="header">Header</h2>
</details>

@eneko
Copy link

eneko commented Oct 26, 2017

Oh man, that works like a charm! 👍. Thank you very much!

Here is some working examples:
https://github.com/eneko/MarkdownGenerator/blob/master/docs/structs/MarkdownHeader.md
http://www.enekoalonso.com/MarkdownGenerator/structs/MarkdownHeader.html

aviflax pushed a commit to FundingCircle/fc4-framework that referenced this issue Sep 5, 2019
This was inspired by [this excellent talk][talk] by Daniele Procida
wherein he said that tutorials (which I *think* this is) should have no
extra material, no explanations. I’m not quite ready to delete these
asides; I feel they are useful content and might be worth keeping
somewhere! But for now at least I can collapse them so that people won’t
be distracted by them unless they want to be.

I found the `markdown="span"` trick in [this issue][issue].

[talk]: https://www.youtube.com/watch?v=azf6yzuJt54
[issue]: gettalong/kramdown#155 (comment)
aviflax pushed a commit to aviflax/fc4 that referenced this issue Sep 17, 2019
This was inspired by [this excellent talk][talk] by Daniele Procida
wherein he said that tutorials (which I *think* this is) should have no
extra material, no explanations. I’m not quite ready to delete these
asides; I feel they are useful content and might be worth keeping
somewhere! But for now at least I can collapse them so that people won’t
be distracted by them unless they want to be.

I found the `markdown="span"` trick in [this issue][issue].

[talk]: https://www.youtube.com/watch?v=azf6yzuJt54
[issue]: gettalong/kramdown#155 (comment)
aviflax pushed a commit to FundingCircle/fc4-framework that referenced this issue Dec 10, 2019
This was inspired by [this excellent talk][talk] by Daniele Procida
wherein he said that tutorials (which I *think* this is) should have no
extra material, no explanations. I’m not quite ready to delete these
asides; I feel they are useful content and might be worth keeping
somewhere! But for now at least I can collapse them so that people won’t
be distracted by them unless they want to be.

I found the `markdown="span"` trick in [this issue][issue].

[talk]: https://www.youtube.com/watch?v=azf6yzuJt54
[issue]: gettalong/kramdown#155 (comment)
aviflax pushed a commit to FundingCircle/fc4-framework that referenced this issue Jan 7, 2020
This was inspired by [this excellent talk][talk] by Daniele Procida
wherein he said that tutorials (which I *think* this is) should have no
extra material, no explanations. I’m not quite ready to delete these
asides; I feel they are useful content and might be worth keeping
somewhere! But for now at least I can collapse them so that people won’t
be distracted by them unless they want to be.

I found the `markdown="span"` trick in [this issue][issue].

[talk]: https://www.youtube.com/watch?v=azf6yzuJt54
[issue]: gettalong/kramdown#155 (comment)
aviflax pushed a commit to FundingCircle/fc4-framework that referenced this issue Jan 7, 2020
Refs #139

[docs] Add framework definition to getting started guide

Along with link to the home page (readme, in the repo)

[docs] Add link to getting started guide to home page

WIP++ Start adding basics part/page

WIP++ add “basics” diagram

WIP++

WIP++

WIP++ Getting Started Guide » Basics

WIP++ move all new docs into the docs dir

WIP++ I begrudgingly agreed to go with data-stores instead of datastores

You win this time, Charles!

WIP++ tweaks, fixes, minor updates

WIP++ TODO! Synchronize definitions of FC4 AND call it a Docs as Data Framework

I *think* that’s correct but I need to confirm and I need to find a link.

[docs] Address errors reported by bin/lint-markdown

WIP++ Fix how asides are rendered

Their contents weren’t being rendered properly because apparently
Kramdown, the default Markdown processor of our SSB software Jekyll
(which is required if I want GitHub pages to build the site) doesn’t
process Markdown inside of HTML tags by default. So I had to add the
config file to override that default.

WIP++ Collapse asides by default

This was inspired by [this excellent talk][talk] by Daniele Procida
wherein he said that tutorials (which I *think* this is) should have no
extra material, no explanations. I’m not quite ready to delete these
asides; I feel they are useful content and might be worth keeping
somewhere! But for now at least I can collapse them so that people won’t
be distracted by them unless they want to be.

I found the `markdown="span"` trick in [this issue][issue].

[talk]: https://www.youtube.com/watch?v=azf6yzuJt54
[issue]: gettalong/kramdown#155 (comment)

[skip CI] WIP++ fix some typos

[skip CI] Use `datastore` and `datatype` consistently

I discussed with Charles and basically I wore him down and he doesn’t care anymore 😬

WIP++
@Eliav2
Copy link

Eliav2 commented May 5, 2021

adding markdown='span' so <summary/> become summery <summary markdown='span'/> to work this out is nice workaround, but we are in 2021 and it should not be neccecary. it also tool me A LOT of time to find out.

@anzz1
Copy link

anzz1 commented Jan 9, 2022

for someone else trying to find a solution for github comments. I found that adding a non-breaking space character (nbsp) aka extended-ascii code 255   character right before <details> makes it work. ALT+255 on Windows. It's kinda ridiculous but yeah.

(ALT+255)<details><summary>Summary Goes Here</summary>
### Header
* option 1
* option 2
* option 3
</details>

becomes
 

Summary Goes Here

Header

  • option 1
  • option 2
  • option 3

@souravdas142
Copy link

souravdas142 commented Jan 29, 2022

Ref : root-project/web#529 (comment) (Thanks 👏 )

If we do something like:

<details markdown=1><summary markdown="span">Our summary here</summary>

our markdown text here : 
```bash
echo "Hello markdown"
``'

- markdown1
- markdown2
- markdown3

html tags also supported
<ol>
<li> hello html list tag1</li>
<li> hello html list tag2</li>
</ol>

</details>

it will be rendered something like :

Our summary here

our markdown text here :

echo "Hello markdown"
  • markdown1
  • markdown2
  • markdown3

html tags also supported

  1. hello html list tag1
  2. hello html list tag2



Edit - 1 - Its to rendering properly on github page

See : https://pipewire-debian.github.io

@berto
Copy link

berto commented Jan 10, 2023

@souravdas142 your solution worked perfectly for me as part of GitHub /github pages with markdown

dev-onejun added a commit to dev-onejun/dev-onejun that referenced this issue Jan 16, 2023
dev-onejun added a commit to dev-onejun/dev-onejun that referenced this issue Jan 16, 2023
dev-onejun added a commit to dev-onejun/dev-onejun that referenced this issue Jan 24, 2023
* Update README.md

* UPDATE: remove nest.js study repository

* UPDATE: add K-SW Square Program in Experience

* UPDATE: add <details> html tags

* UPDATE: link to Weltried project

* UPDATE: the breaking html tags with gettalong/kramdown#155

* UPDATE: add the contribution repository `pynecone`

* UPDATE: format of Experience

* DELETE: github readme badge
ameaninglessname pushed a commit to RemRemRemRe/RemRemRemRe.github.io that referenced this issue Jun 9, 2023
@WebReflection
Copy link

to whom it might concern, I've solved the issue by adding markdown=1 to an inner <div>:

<details>
  <summary><strong>A strong summary</strong></summary>
  <div markdown=1>

This is fine:
  * first
  * second

  </div>
</details>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

8 participants