When I read the official documentation, it only mentioned the {% highlight python %} syntax:
https://jekyllrb.com/docs/templates/
However I prefer to use the backticks code block to highlight codes in markdowns:
```python
code goes here
```
I googled around and found a few requests but I'm not sure if the backticks work right now. If it works, how can I enable it? As I experimented with my own jekyll github page and it still only works with {% highlight python %}.
It seems that the kramdown is only on Jekyll 3.X. Unfortunately, the theme that I'm using is on 2.X.
https://cecilialee.github.io/
How can I work on it? Would I be able to update my theme to Jekyll 3.X without breaking anything? Or how can I add the function to my current Jekyll site?
Yes backticks and ~ also work for highlighting code without further configuration. Jekyll uses Kramdown by default which supports backtick fenced code blocks.
Following your example:
```python
fun test_me():
print('yes, backticks work!')
```
produces:
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">fun</span> <span class="n">test_me</span><span class="p">():</span>
<span class="k">print</span><span class="p">(</span><span class="s">'yes, backticks work!'</span><span class="p">)</span>
</code></pre>
</div>
Related
In my current Jekyll setup I am writing all my posts using the asciidoc (.adoc) file format, specifically I'm using these plugins
plugins:
- jekyll-asciidoc
- jekyll-redirect-from
- jekyll-feed
I am in need to create a custom HTML component which I have added in component.html under the _includes folder, following the includes feature of Jekyll.
I am able at the moment to use Liquid in a Markdown file to render the HTML component by just using
{% include component.html %}
at any point in my posts, but I can't do the same with asciidoc files. I've taken a look at their documentation and I can't find a suitable way to make use of this Jekyll feature.
Is there a way to use Liquid in asciidoc?
After a little bit of research I've found a couple of things with which I was able to inject _includes HTML components in an asciidoc file.
jekyll-asciidoc has a special page attribute to enable Liquid preprocessing, you can find the docs at :page-liquid:
So, in order to enable Liquid preprocessing you just have to add this to the asciidoc post
:page-liquid:
With this, Jekyll is going to parse every Liquid statement in your file before actually passing it to the asciidoc generator.
The post needs another little change at this point, citing the docs:
If you’re using the Liquid include tag to include HTML into the AsciiDoc document, enclose it in a passthrough block.
++++
{% include file.html %}
++++
By default :page-liquid: will escape Liquid generated content, which is why you need to enclose the {% include ... %} statement in the asciidoc Passthrough construct ++++ that is going to inject raw HTML into the page itself.
In conclusion, this is what an example post should look like:
_includes/component.html
<p>Some sample text</p>
_posts/liquid-in-asciidoc.adoc
---
title: "HTML component in adoc
---
:page-liquid:
++++
{% include component.html %}
++++
I have the code like this:
<div class="my-super-class {{#if something}}{{else}}hidden{{/if}}">
Notice the space after 'my-super-class'
Problem:
If to minify this code snippet the space will be removed and we'll get my-super-classhidden class instead of my-super-class hidden.
How to resolve this issue without npm installations?
You should run html-minifier from the command line, with the option
--ignore-custom-fragments "/{{[{]?(.*?)[}]?}}/"
This regex will ignore everything between {{ and }} and minify the rest
PS: you can also add the space right before hidden
<div class="my-super-class{{#if something}}{{else}} hidden{{/if}}">
I haven't found something valuable. The only way for now is to install this minifier and run it on node.js. It also can be well configured in many desired ways. It understands handlebars.js and minifies HTML better than other known minify services.
I use jekyll to write post and show it in GitHub-pages. My source file is written with markdown.
How can I insert formula into the markdown file?
I don't want to save the formula into an image and load the image in markdown file. I actually want to write latex formula in markdown file directly.
Since resources online have changed regarding this question, here's an update on supporting LateX with GitHub Pages.
Note that the closest to Latex rendering without exporting as images and natively supporting it on your Jekyll site would be to use MathJax.
MathJax is actually recommended in Jekyllrb docs for math support, with Kramdown, it also converts it from LaTeX to PNG, more details on it here at the Kramdown documentation
Option 1: Write your equation in MathURL and embed it.
You could write the equation with MathURL, then generate a url that permanently points to the equation, and display this in an <iframe> tag. However, this will stop working if MathURL goes offline.
Option 2: Implement jsMath
jsMath will allow almost LateX like syntax and will be supported in your blog if you have set it up correctly, there is extensive documentation on this.
Option 3: Mathjax (by far the easiest in my opinion)
Many sites have mentioned that Mathjax is considered a successor of jsMath, and is much easier to implement with Jekyll. MathJax is also used by mathematics.stackexchange.com too!
Step 1: Have your site load the script in sites where you want to display math. (usually done in the header)
Optional: Check your markdown parser in _config.yml. redcarpet or kramdown is suggested in this example. Certain parsers like discount will interfere with the syntax but I have a solution below.
Step 2: Write your equations.
Quoting this tutorial by Gaston Sanchez:
MathJax does not have the exactly same behavior as LaTeX. By default,
the tex2jax preprocessor defines the LaTeX math delimiters, which are
\(...\) for in-line math, and \[...\] for displayed equations. It
also defines the TeX delimiters $$...$$ for displayed equations, but
it does not define $...$ as in-line math delimiters.
Read the documentation on the syntax for more details.
Note: Using the raw liquid tag to ensure Markdown parsers do not interfere with MathJax syntax.
While you could escape backslashes (e.g. \\[ \frac{1}{n^{2}} \\])to
ensure they are parsed properly, as described by Chistopher Poole's
tutorial, this is not always intuitive and looks complicated. A
simpler solution would be to use the raw liquid tag to ensure the
text is ignored by the Markdown processor and directly output as a
static html. This is done with {% raw %}and also {% endraw %}
Here is a code sample:
{% raw %}
$$a^2 + b^2 = c^2$$ --> note that all equations between these tags will not need escaping!
{% endraw %}
Lastly also ensure that the fonts support displaying LateX as some have issues like font size being too small. Alternatively here are some additional methods like Google Charts and MathML discussed in the latex StackExchange sister site.
If you used Jekyll in your GitHub pages, you can add
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
inlineMath: [['$','$']]
}
});
</script>
<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
in the file _includes/head.html, and then your GitHub Pages site will support MathJax
The easiest way to do this right now is to use the KaTeX auto-render extension.
Simply drop the following into your <head>:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex#0.10.2/dist/katex.min.css" integrity="sha384-yFRtMMDnQtDRO8rLpMIKrtPCD5jdktao2TV19YiZYWMDkUR5GQZR/NOVTdquEx1j" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex#0.10.2/dist/katex.min.js" integrity="sha384-9Nhn55MVVN0/4OFx7EE5kpFBPsEMZxKTCnA+4fqDmg12eCTqGi6+BB2LjY8brQxJ" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex#0.10.2/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>
Note that this assumes the following delimiters appear in your HTML:
$$\LaTeX code$$ (for display)
\\[\LaTeX code\\] (also for display)
\\(\LaTeX code\\) (for inline)
Note, if using Jekyll, you will need to have the following in your _config.yml:
markdown: kramdown
kramdown:
math_engine: katex
WARNING: Do not use math_engine: mathjax. It will break this by automatically removing the LaTeX delimiters.
Unfortunately most answers here are outdated nowadays. Github renders your markdown files using kramdown . Annoyingly kramdown defines math content differently from other markdown variants. In kramdown inline math is written using $$ as delimiter like text $$ E = mc^2 $$ text. Display math is also written using $$ delimiter, but it must be separated from the text by a blank line
text
$$\begin{aligned}
E = mc^2
\end{aligned}$$
text
Kramdown will render the inline math as \( E = mc^2 \) and the display math as
\[\begin{aligned}
E = mc^2
\end{aligned}\]
in your output HTML. These are also the delimiters used by mathjax as default. Therefore to configure MathJax 3 for github pages it is enough to add
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax#3/es5/tex-mml-chtml.js"></script>
to the file _includes/head-custom.html. You don't need to create or modify the _config.yml file.
I recommend you to use MathJax 3 over KaTeX, because MathJax 3 is not much slower anymore than KaTeX (see https://www.intmath.com/cg5/katex-mathjax-comparison.php) and supports more features (E.g. KaTex cannot handle \label and \eqref (see https://github.com/KaTeX/KaTeX/issues/2003))
If you still want to use https://katex.org/docs/autorender.html you must add
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex#0.15.6/dist/katex.min.css" integrity="sha384-ZPe7yZ91iWxYumsBEOn7ieg8q/o+qh/hQpSaPow8T6BwALcXSCS6C6fSRPIAnTQs" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex#0.15.6/dist/katex.min.js" integrity="sha384-ljao5I1l+8KYFXG7LNEA7DyaFvuvSCmedUf6Y6JI7LJqiu8q5dEivP2nDdFH31V4" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex#0.15.6/dist/contrib/auto-render.min.js" integrity="sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR" crossorigin="anonymous"
onload="renderMathInElement(document.body);"></script>
to the file _includes/head-custom.html. You don't need to create or modify the _config.yml file.
Note: I tried to use github flavored markdown renderer instead of the default renderer for github pages by setting markdown: GFM in the the _config.yml file. This would give you additional features like autolinks ( see https://github.community/t/github-pages-autolinks-fail/129713/4 ) and the more common $ delimiter for inline math and $$ delimiter for display math (https://github.blog/2022-05-19-math-support-in-markdown/) as it is supported by https://pandoc.org/. However the GFM markdown renderer from github has still many, many problems with math section making it unusable (https://nschloe.github.io/2022/05/20/math-on-github.html).
A while ago I created xhub, a browser extension that allows you to use math in github pages.
Cons:
You have to install the extension.
Pros:
No need to set up any workflow.
Just edit your markdown as usual and use
Display math:
```math
e^{i\pi} + 1 = 0
```
and inline math $`a^2 + b^2 = c^2`$.
(Syntax just like on GitLab.)
Works well on light and dark background.
You can even copy-and-paste the math!
Perhaps worth checking out.
I would like this to be a comment on daviewales answer but I do not have enough reputation unfortunately. My understanding of that answer is to copy the 3 lines of code into the file <your_repo>.github.io\_site\<postname>\index.html. However, that file seems to get updated each time the corresponding <postname>.md is edited. Is there a more elegant way to always get those lines of code automatically added to the html file, without having to manually edit it every time I want to check an equation?
EDIT:
I think this is one solution to the above problem:
What ended up working for me was based off of PeaShooter's response. I made a folder _includes within my _posts folder, and then populated it with a file head.html containing the code from PeaShooter's answer. Then, in the top line of the post below the YAML front matter (i.e. below the second --- line) I put the code {% include_relative _includes/head.html %}
Note that it was important to make the _includes folder not in base folder <your_repo>.github.io, but within the _posts folder. While placing _includes in the base folder did automatically generate the equation, it ruined the formatting for the rest of the website.
The best way right now IMO is to use the MathJax backend (which is part of kramdown, i.e. available on GitHub Pages) and then use KaTeX on the frontend for rendering. KaTeX is more lightweight and faster than MathJax, which makes it a better fit for a blog theme.
I'm using this technique with great success for my Jekyll theme Hydejack. Feel free to use it on your own site, by doing the following:
In config.yml, set the math engine to mathjax:
kramdown:
math_engine: mathjax
Add KaTeX to your site and also make sure the following code runs sometime after it has loaded.
const mathBlocks = document.querySelectorAll('script[type^="math/tex"]');
Array.from(mathBlocks).forEach((el) => {
const tex = el.textContent.replace("% <![CDATA[", "").replace("%]]>", "");
el.outerHTML = window.katex.renderToString(tex, {
displayMode: el.type === "math/tex; mode=display",
});
});
The actual code I'm using is slightly more complicated. You can check it out on GitHub.
Some of the answers are a bit complicated or even outdated so here's a recent solution that works well for me. You can solve the problem using layouts.
Create a folder _layouts to the folder from which you publish (for example docs/).
Create default.html. This will be the layout for all your pages. If you have just started your page, you can use this as a template for the default.html file:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>{{ page.title }}</title>
</head>
<body>
{{ content }}
</body>
</html>
Then add this script before </html>:
<script
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
type="text/javascript">
</script>
I had the problem that I was using minima theme. So if I applied the change above I lost my theme in my posts. I went to the github repo and copied whatever they had in default.html and added the script above before </html> and it worked!
I found out the answer here.
I'm using Markdown in Jekyll v1.4.2 for Windows, and I currently have my excerpt tag set to "<--excerpt-->"
However when I put the comment tag in my .markdown file as follows:
blog entry excerpt is here
<!--excerpt-->
blog entry continues
Jekyll converts the < and > in the comment tags to > and <, and the comment shows up in my final HTML, which looks like this:
<p> blog entry excerpt is here <!--excerpt></p>
<p> blog entry continues</p>
Funnily, the tag is still recognized and excerpt works in the blog
To get the tag as an actual comment, I have to do this:
blog entry excerpt is here
<!--excerpt-->
blog entry continues
which gives me:
<p> blog entry excerpt is here</p>
<!--excerpt-->
<p> blog entry continues</p>
Is this intended behavior in Jekyll? I couldn't find anybody else with this issue and it took me hours to figure out, so hopefully at the very least this is helping someone else.
It looks like this is the intended behavior for Jekyll and its Markdown processor. Per the Markdown specification for Paragraph elements,
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines.
Essentially, your excerpt was being interpreted as part of the Paragraph element. When you added the blank line between your Comment and the preceding line, it was then placed after the closing </p> tag, and appeared as you intended.
Use the redcarpet markdown parser ... it is much for forgiving, more easily allowing you to to use HTML in .md files. (without the HTML markup showing up where you don't want it)
cd your/project/dir
gem install redcarpet
bundle install
add this line to your Gemfile ⇨ gem 'redcarpet'
add this line to your _config.yml ⇨ markdown: redcarpet
This has worked for me when I wanted to use HTML in .md, but the html markup itself was being rendered into the served page.
Hope it works for you!
I want to use kramdown (with features such as fenced code blocks, inline attribute lists, header IDs) together with pygments for syntax highlighting (e.g. for LaTeX support, which is not available with CodeRay used by kramdown). Jekyll supports both kramdown and pygments, but apparently not the two together (unless I use Liquid tags which I would prefer not to).
I've also found some plugin snippets of how to make kramdown fenced code blocks spit pygments highlighted code, but unfortunately I don't know how to make that work.
I tried dumping all of the code from that site on some _plugins/krampygs.rb file, but then jekyll build complains about:
Generating... error: undefined method `matches'
If I supply some trivial matches and output_ext as instructed by Jekyll plugin docs, but then I don't know how to select this new converter for my .md files. Adding something like
markdown: MarkdownConverter
on my _config.yml only complains that this is not a valid option.
So, well, I restate my question: How can I use kramdown with pygments in Jekyll?
Solution
With the help of Matthias (below), I was able to prepare this Kramdown+Pygments plugin for Jekyll 1.x.
Author of "that site" here.
It depends on the Jekyll version. For the version when the post was written, that was enough. At least Jekyll 1.x requires that matches is defined in the MarkdownConverter, like so:
def matches(ext)
ext =~ /^\.md$/i
end
Another problem that appears with Jekyll 1.x is that every custom Markdown converter is ignored. I worked around this by by stating the output extension explicitly
def output_ext(ext)
".html"
end
and tell Jekyll that to look for a bogus Markdown extension by setting
markdown_ext: foo
in _config.yml.
I have updated the plugin created by Juan, to be compatible with Jekyll 2.x, along with some other improvements.
It can be found here: https://github.com/mvdbos/kramdown-with-pygments.git