Replace backticks within HTML blocks with HTML tags #5435

alexmalik · 2016-10-01T22:42:08Z

Prior to the change backticks were used in an attempt to create a
code block. The problem is that inside block level HTML tags Markdown
is not supported. I have replaced the backticks with a combination of
HTML tags in order to approximately simulate the appearance of a code
block. The docs suggest possible use of span tags in place of the
surrounding div tags as a solution to getting the Markdown to render.
I tried this but no success.

This change improves the readers understanding of the information,
because the reader doesn't have to make sense of raw markdown.

pathawks · 2016-10-01T22:57:50Z

This seems to make things more difficult to read. Why is the code block broken up between multiple <p>?

I don't think I understand the problem being fixed here.

ashmaroli · 2016-10-02T02:17:05Z

A screenshot helps in putting the point forward..

Issue Screengrab

ashmaroli · 2016-10-02T02:23:11Z

I'm not in favour of using multiple <p></p> tags here. Please simulate a generated code block by using <pre class="highlight"><code>[code-block]</code></pre> Its not entirely correct either.. you wont get the lines to highlight, but you can simulate the code block at a fine extent.

Pro-Tip: Don't forget to preview your changes to site before pushing.
You can do so by running bundle exec rake site:preview

/cc @jekyll/documentation

ashmaroli · 2016-10-02T02:29:03Z

Also, I'd suggest the title to be edited to :
Replace backticks within HTML blocks with HTML tags

pathawks · 2016-10-02T04:07:22Z

@ashmaroli Thank you; that is the part I was missing.

Could we use the {% highlight %} tag?

ashmaroli · 2016-10-02T04:29:44Z

@pathawks, you're welcome. :)
I'd tried {% highlight ruby %} the resulting code block highlighted the ruby syntax correctly, but the overall styling was a bit out of place.. Maybe I could have got it to work if I played around a bit.. but I decided to let the contributor discover that by himself..

alexmalik · 2016-10-02T12:37:15Z

Thanks for your feedback on the PR everyone :)
@ashmaroli thank you especially for the tips!

envygeeks · 2016-10-02T16:36:42Z

We no longer use {% highlight %} in Jekyll's site source, it was optioned and voted to start using triple backticks, this was done not too long ago, so unless you absolutely need highlight, you should properly space out your backticks and use those.

ashmaroli · 2016-10-02T17:16:25Z

so unless you absolutely need highlight,

@envygeeks, this is one such instance where I think we absolutely need to use highlight. I authored the commit that replaced {% highlight %} with backticks. What I didnt know till now, was that backticks dont seem to get picked up as expected when they are inside an HTML element.

ashmaroli · 2016-10-02T17:51:09Z

@alexmalik, I tested your branch locally. This is the problem with using {% highlight %}.

The best solution would hence be to manually code the blocks in HTML.
few tips:

HTML generated by backticks is slightly different from that generated by highlight
The former gives you a div with class="highlighter-rouge", while that latter gives you a figure with class="highlight"
You dont have to manually code the syntax highlight spans. It's already available in your branch inside _site/docs/github-pages/index.html
The same page has another block generated by backticks above the current scene of action. That'll tell you how your own code should look like.

pathawks · 2016-10-03T04:32:24Z

This is the problem with using {% highlight %}.

Looks like it's just a problem with CSS, not with the tag itself.

ashmaroli · 2016-10-03T04:51:43Z

@pathawks, like I mentioned above, the markup differs too:
{% highlight ruby %} generates :

<figure class="highlight">
  <pre>
    <code class="language-ruby" data-lang="ruby">
      <span></span>
    </code>
  </pre>
</figure>

while backticks ruby generates

<div class="language-ruby highlighter-rouge">
  <pre class="highlight">
    <code>
      <span></span>
    </code>
  </pre>
</div>

mmistakes · 2016-10-03T16:46:42Z

@ashmaroli Kramdown has a mechanism for parsing Markdown inside of HTML. If you wrap it with something like a <div> element and give it an attribute of markdown="1" it'll process triple backticks (or any other Markdown).

<div markdown="1">
  triple backtick code bloc
</div>

Still doesn't fix the CSS that will likely need to be adjusted for .note, but at least you don't have to manually simulate Rouge's output.

ashmaroli · 2016-10-03T17:04:03Z

niceee.. 👍
Thank you @mmistakes 😃

@alexmalik

the use of this attribute allows kramdown to parse markdown within HTML elements. More info can be found here: http://kramdown.gettalong.org/syntax.html#html-blocks Thanks: - @alexmalik (https://github.com/alexmalik) for starting the pull request at jekyll#5435 which highlighted the issue and led to this. - Michael Rose (https://github.com/mmistakes) for bringing this attribute to my attention.

@alexmalik

the use of this attribute allows kramdown to parse markdown within HTML elements. More info can be found here: http://kramdown.gettalong.org/syntax.html#html-blocks Thanks: - @alexmalik for starting the pull request at jekyll#5435 which highlighted the issue and led to this. - Michael Rose (@mmistakes) for bringing this attribute to my attention.

ashmaroli · 2016-10-04T07:34:01Z

It looks like GFM doesnt work like kramdown in this regard too..
GFM seems to require an empty closed <element> with markdown="1" to be present for every nested html element within the concerned element..

Confused?
Check this branch compare on my fork to understand.

@alexmalik : you're welcome to cherry-pick the commits on that branch to yours, or manually commit them to your branch, whichever way you prefer to, for review here.

ashmaroli · 2016-10-04T11:31:04Z

@alexmalik, the reason we decided to use backticks over {% highlight %} is because by using backticks, markdown pages can be viewed as intended, even at the repo instead of only at jekyllrb.com
If you VIEW the github-pages.md in your branch, you'll see that the section under consideration does not have the fenced-code block rendered properly. Hence you need to implement the second commit in my branch-compare as well.

alexmalik · 2016-10-04T11:39:33Z

@ashmaroli it looks ok to me, the slightly darker background of the code blocks is removed, improving the uniformity. Is this ok?

ashmaroli · 2016-10-04T11:53:25Z

@alexmalik, the page at jekyllrb looks 👍
but look how it is at Github..

the page on your branch..

the page on mine..

ashmaroli

now its proper 👍

pathawks

Thank you so much for working on this.

My only concern is that I would like to see Markdown style links ([]()) used instead of HTML links (<a href="">)

Everything else looks good to me 👍

pathawks · 2016-10-21T04:19:59Z

site/_docs/github-pages.md

+##### Use the `github-pages` gem
+
+Our friends at GitHub have provided the
+<a href="https://github.com/github/pages-gem">github-pages</a>


Can we make this a Markdown style link?

[github-pages](https://github.com/github/pages-gem)

pathawks · 2016-10-21T04:20:49Z

site/_docs/github-pages.md


-    If you like to install <code>pages-gem</code> on Windows you can find instructions by Jens Willmer on <a href="http://jwillmer.de/blog/tutorial/how-to-install-jekyll-and-pages-gem-on-windows-10-x46#github-pages-and-plugins">how to install github-pages gem on Windows (x64)</a>.
-  </p>
+If you like to install `pages-gem` on Windows you can find instructions by Jens Willmer on <a href="http://jwillmer.de/blog/tutorial/how-to-install-jekyll-and-pages-gem-on-windows-10-x46#github-pages-and-plugins">how to install github-pages gem on Windows (x64)</a>.


Can we use a Markdown style link here as well?

DirtyF · 2016-11-09T21:53:00Z

hey @alexmalik sorry for not merging this sooner, could you rebase this please now that the docs have moved to /docs/_docs/?

envygeeks · 2016-11-20T19:33:39Z

I'll 👍 after a rebase!

Prior to the change backticks were used in an attempt to create a code block. The problem is that inside block level HTML tags Markdown is not supported. I have replaced the backticks with a combination of HTML tags in order to approximately simulate the appearance of a code block. The docs suggest possible use of span tags in place of the surrounding div tags as a solution to getting the Markdown to render. I tried this but no success. This change improves the readers understanding of the information, because the reader doesn't have to make sense of raw markdown.

@mmistakes

uses Kramdown with the markdown="1" attribute, as suggested by @mmistakes. This allows rendering of code blocks which are nested inside HTML tags.

@ashmaroli

as suggested by @ashmaroli

an empty div is necessary in order for the code blocks to render correctly when not displayed on the jekyllrb site.

pathawks · 2016-11-20T20:06:06Z

Rebased 1b3cf68 onto master ✅

DirtyF · 2016-11-20T23:06:45Z

Thanks everyone for helping fix this rendering issue.

@jekyllbot: merge +site

alexmalik · 2016-11-21T10:12:27Z

Thanks for your help everyone 👍

djacquel · 2017-01-27T20:00:32Z

Setting a :

kramdown:
  parse_block_html: true

was enough for me to fix this.

jekyllbot assigned DirtyF Oct 2, 2016

alexmalik changed the title ~~Replace backticks with HTML tags~~ Replace backticks within HTML blocks with HTML tags Oct 2, 2016

parkr added the documentation label Oct 3, 2016

ashmaroli approved these changes Oct 4, 2016

View reviewed changes

pathawks requested changes Oct 21, 2016

View reviewed changes

This was referenced Oct 21, 2016

Update github-pages.md #5503

Closed

github-pages ProTip doesn't format code #5506

Closed

DirtyF added the pending-rebase label Nov 9, 2016

pathawks approved these changes Nov 20, 2016

View reviewed changes

alexmalik added 6 commits November 20, 2016 13:42

Replace p and code tags with {% highlight %}

c47ae46

replace {% %} with bacticks for nested code-block

a41b46f

uses Kramdown with the markdown="1" attribute, as suggested by @mmistakes. This allows rendering of code blocks which are nested inside HTML tags.

add new style rule for .code-block class

2009749

as suggested by @ashmaroli

add empty div with markdown="1" attribute

9cd71aa

an empty div is necessary in order for the code blocks to render correctly when not displayed on the jekyllrb site.

Replace html links with markdown links

df80f6f

jekyllbot removed the pending-rebase label Nov 20, 2016

envygeeks approved these changes Nov 20, 2016

View reviewed changes

DirtyF closed this Nov 20, 2016

jekyllbot merged commit 1936c21 into jekyll:master Nov 20, 2016

jekyllbot added the documentation label Nov 20, 2016

jekyllbot added a commit that referenced this pull request Nov 20, 2016

Update history to reflect merge of #5435 [ci skip]

8a08bb4

alexmalik deleted the github-pages-backticks branch November 21, 2016 10:12

jekyll locked and limited conversation to collaborators Jul 11, 2019

jekyllbot added the frozen-due-to-age label Jul 11, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace backticks within HTML blocks with HTML tags #5435

Replace backticks within HTML blocks with HTML tags #5435

alexmalik commented Oct 1, 2016

pathawks commented Oct 1, 2016

ashmaroli commented Oct 2, 2016

ashmaroli commented Oct 2, 2016 •

edited

Loading

ashmaroli commented Oct 2, 2016

pathawks commented Oct 2, 2016

ashmaroli commented Oct 2, 2016

alexmalik commented Oct 2, 2016

envygeeks commented Oct 2, 2016

ashmaroli commented Oct 2, 2016 •

edited

Loading

ashmaroli commented Oct 2, 2016

pathawks commented Oct 3, 2016

ashmaroli commented Oct 3, 2016

mmistakes commented Oct 3, 2016 •

edited

Loading

ashmaroli commented Oct 3, 2016

ashmaroli commented Oct 4, 2016

ashmaroli commented Oct 4, 2016 •

edited

Loading

alexmalik commented Oct 4, 2016

ashmaroli commented Oct 4, 2016

ashmaroli left a comment

pathawks left a comment

pathawks Oct 21, 2016

pathawks Oct 21, 2016

DirtyF commented Nov 9, 2016

envygeeks commented Nov 20, 2016

pathawks commented Nov 20, 2016

DirtyF commented Nov 20, 2016

alexmalik commented Nov 21, 2016

djacquel commented Jan 27, 2017

Replace backticks within HTML blocks with HTML tags #5435

Replace backticks within HTML blocks with HTML tags #5435

Conversation

alexmalik commented Oct 1, 2016

pathawks commented Oct 1, 2016

ashmaroli commented Oct 2, 2016

Issue Screengrab

ashmaroli commented Oct 2, 2016 • edited Loading

ashmaroli commented Oct 2, 2016

pathawks commented Oct 2, 2016

ashmaroli commented Oct 2, 2016

alexmalik commented Oct 2, 2016

envygeeks commented Oct 2, 2016

ashmaroli commented Oct 2, 2016 • edited Loading

ashmaroli commented Oct 2, 2016

pathawks commented Oct 3, 2016

ashmaroli commented Oct 3, 2016

mmistakes commented Oct 3, 2016 • edited Loading

ashmaroli commented Oct 3, 2016

ashmaroli commented Oct 4, 2016

ashmaroli commented Oct 4, 2016 • edited Loading

alexmalik commented Oct 4, 2016

ashmaroli commented Oct 4, 2016

the page on your branch..

the page on mine..

ashmaroli left a comment

Choose a reason for hiding this comment

pathawks left a comment

Choose a reason for hiding this comment

pathawks Oct 21, 2016

Choose a reason for hiding this comment

pathawks Oct 21, 2016

Choose a reason for hiding this comment

DirtyF commented Nov 9, 2016

envygeeks commented Nov 20, 2016

pathawks commented Nov 20, 2016

DirtyF commented Nov 20, 2016

alexmalik commented Nov 21, 2016

djacquel commented Jan 27, 2017

ashmaroli commented Oct 2, 2016 •

edited

Loading

ashmaroli commented Oct 2, 2016 •

edited

Loading

mmistakes commented Oct 3, 2016 •

edited

Loading

ashmaroli commented Oct 4, 2016 •

edited

Loading