My GitHub repository has nothing but a readme in it. In this readme, locally I wrote this:
Factoids:
- There are about six different ways to do everything in Forked.
- There are actually six different ways to enter loops.
- There are six directionals and six I/O commands.
- 666. ha.
Emphasis on the last line.
What GitHub decided to show was not 666.
DCLXVI is the Roman Numeral number for 666.
This really creeped me out. My local file and the raw file both show 666.
What is GitHub doing, and why is the indentation on the un-numbered list messed up? Is this an easter egg, or some satanic bug?
This seems to be followed by github/markup issue 991, where on ordered sub-list, decimal numerals automatically turns into roman numerals.
I have found the cause of problem. It is CSS
This is the expected way for nested ordered lists to render in HTML.
This is not expected in HTML. https://jsfiddle.net/tf5jtv8s
We don't make any modifications to the default HTML behavior.
ol ol,ul ol{list-style-type:lower-roman}
I don't know CSS but my understanding is that this is the cause of problem. I can get expected result by disabling CSS. (I am from my mobile so I can't use browser inspector)
As mentioned in "A formal spec for GitHub Flavored Markdown", GitHub markdown spec GFM: GitHub Flavored Markdown Spec is built on top of the CommonMark Spec.
And as Tommi Kaikkonen mentioned in his answer, the ordered list is because of the dot following 666. See GFM Spec section 5.2.
As mentioned in section 6.1, any ASCII punctuation character may be backslash-escaped, to avoid this issue.
That means:
- 666\. ha.
(as explicitly shown in ForNeVeR's answer)
That is why that 666 number is changed to roman numerals in a GitHub README markdown.
Mike Lippert commented:
the 1st element in that list so it should show as i not dclxvi.
Markdown ordered lists ignore the actual number used and number sequentially, and I haven't seen a way to change that.
However, no: it shows dclxvi, because the generated html code is <ol start="666">, which is consistent with the GFM specs:
If the list item is ordered, then it is also assigned a start number, based on the ordered list marker"
(here, '666' is the ordered list marker)
Mike adds:
#VonC For anyone else here's another useful excerpt from VonC's doc link:
"The start number of an ordered list is determined by the list number of its initial list item. The numbers of subsequent list items are disregarded."
Also, why is the spacing messed up? I didn't catch that in your answer
You get an ordered list <ol> within an un-ordered list item <li>:
<ul>
<li>
<ol start="666">
<li>ha.</li>
</ol>
</li>
</ul>
GitHub CSS rules include:
.markdown-body ol {
padding-left: 2em;
}
If you put 3em, you would get
instead of
Adding a period after 666 makes it an ordered list marker.
GitHub declares CSS that renders ordered list markers using roman numerals:
ol ol,ul ol {
list-style-type: lower-roman
}
Escape the period with a backslash, and you should see the correct output.
While other answers are good at explaining why you have the problem, they haven't given you an exact example of how to fix that.
And it seems that you've already solved it in an imperfect manner, replacing your text with
- `666`. ha.
There's a common trick to escape the dot after the number to make it look like a normal text (and not an ordered list label):
- 666\. ha. (this will render as you probably want)
Related
Is there a standard or convention for embedding metadata in a Markdown formatted post, such as the publication date or post author for conditional rendering by the renderer?
Looks like this Yaml metadata format might be it.
There are all kinds of strategies, e.g. an accompanying file mypost.meta.edn, but I'm hoping to keep it all in one file.
There are two common formats that look very similar but are actually different in some very specific ways. And a third which is very different.
YAML Front Matter
The Jekyll static site generator popularized YAML front matter which is deliminated by YAML section markers. Yes, the dashes are actually part of the YAML syntax. And the metadata is defined using any valid YAML syntax. Here is an example from the Jekyll docs:
---
layout: post
title: Blogging Like a Hacker
---
Note that YAML front matter is not parsed by the Markdown parser, but is removed prior to parsing by Jekyll (or whatever tool you're using) and could actually be used to request a different parser than the default Markdown parser for that page (I don't recall if Jekyll does that, but I have seen some tools which do).
MultiMarkdown Metadata
The older and simpler MultiMarkdown Metadata is actually incorporated into a few Markdown parsers. While it has more recently been updated to optionally support YAML deliminators, traditionally, the metadata ends and the Markdown document begins upon the first blank line (if the first line was blank, then no metadata). And while the syntax looks very similar to YAML, only key-value pairs are supported with no implied types. Here is an example from the MultiMarkdown docs:
Title: A Sample MultiMarkdown Document
Author: Fletcher T. Penney
Date: February 9, 2011
Comment: This is a comment intended to demonstrate
metadata that spans multiple lines, yet
is treated as a single value.
CSS: http://example.com/standard.css
The MultiMarkdown parser includes a bunch of additional options which are unique to that parser, but the key-value metadata is used across multiple parsers. Unfortunately, I have never seen any two which behaved exactly the same. Without the Markdown rules defining such a format everyone has done their own slightly different interpretation resulting in a lot of variety.
The one thing that is more common is the support for YAML deliminators and basic key-value definitions.
Pandoc Title Block
For completeness there is also the Pandoc Title Block. If has a very different syntax and is not easily confused with the other two. To my knowledge, it is only supported by Pandoc (if enabled), and it only supports three types of data: title, author, and date. Here is an example from the Pandoc documentation:
% title
% author(s) (separated by semicolons)
% date
Note that Pandoc Title Blocks are one of two style supported by Pandoc. Pandoc also supports YAML Metadata as described above.
A workaround use standard syntax and compatible with all other viewers.
I was also looking for a way to add application specific metadata to markdown files while make sure the existing viewers such as vscode and github page will ignore added metadata. Also to use extended markdown syntax is not a good idea because I want to make sure my files can be rendered correctly on different viewers.
So here is my solution: at beginning of markdown file, use following syntax to add metadata:
[_metadata_:author]:- "daveying"
[_metadata_:tags]:- "markdown metadata"
This is the standard syntax for link references, and they will not be rendered while your application can extract these data out.
The - after : is just a placeholder for url, I don't use url as value because you cannot have space in urls, but I have scenarios require array values.
Most Markdown renderers seem to support this YAML format for metadata at the top of the file:
---
layout: post
published-on: 1 January 2000
title: Blogging Like a Boss
---
Content goes here.
The most consistent form of metadata that I've found for Markdown is actually HTML meta tags, since most Markdown interpreters recognize HTML tags and will not render meta tags, meaning that metadata can be stored in a way that will not show up in rendered HTML.
<title>Hello World</title>
<meta name="description" content="The quick brown fox jumped over the lazy dog.">
<meta name="author" content="John Smith">
## Heading
Markdown content begins here
You can try this in something like GitHub Gist or StackEdit.
Correct.
Use the yaml front matter key-value syntax — like MultiMarkdown supports — but (ab)use the official markdown URL syntax to add your metadata.
… my workaround looks like this:
---
[//]: # (Title: My Awesome Title)
[//]: # (Author: Alan Smithee)
[//]: # (Date: 2018-04-27)
[//]: # (Comment: This is my awesome comment. Oh yah.)
[//]: # (Tags: #foo, #bar)
[//]: # (CSS: https://path-to-css)
---
Put this block at the top of your .md doc, with no blank line between the top of the doc and the first ---.
Your fake yaml won't be included when you render to HTML, etc. … it only appears in the .md.
You can also use this technique for adding comments in the body of a markdown doc.
This is not a standard way, but works with Markdown Extra.
I wanted something that worked in the parser, but also didn't leave any clutter when I browse the files on Bitbucket where I store the files.
So I use Abbreviations from the Markdown Extra syntax.
*[blog-date]: 2018-04-27
*[blog-tags]: foo,bar
then I parse them with regexp:
^\*\[blog-date\]:\s*(.+)\s*$
As long as I don't write the exact keywords in the text, they leave no trace. So use some prefix obscure enough to hide them.
I haven't seen this mentioned elsewhere here or in various blogs discussing the subject, but in a project for my personal website, I've decided to use a simple JSON object at the top of each markdown file to store metadata. It's a little more cumbersome to type compared to some of the more textual formats above, but it's super easy to parse. Basically I just do a regex such as ^\s*({.*?})\s*(.*)$ (with the s option on to treat . as \n) to capture the json and markdown content, then parse the json with the language's standard method. It allows pretty easily for arbitrary meta fields.
I am talking about github markdown here, for files like README.md.
Question:
Is it possible to strikethrough a complete code block in markdown on github?
I know how to mark text as a block of code
this is
multiline code
and
this
this
also
by indenting by 4 spaces or by using ``` or `...
I also know how to strike through texts using
del tag
s tag
~~
Temporary solution:
Independently they work fine, but together not as expected or desired. I tried several combinations of the above mentioned.
For now, I use this:
striked
through
by using ~~ and ` for every single line.
Requirement:
I would like to have a code formatted text striked through, where the code block is continuous:
unfortunately, this is
not striked through
or at least with only a small paragraph in between:
unfortunately, also not
striked through
Is this possible at all?
I found some old posts and hints on using jekyll, but what I was searching for is a simple way, preferably in markdown.
This would only be possible with raw HTML, which GitHub doesn't allow. But you may be able to use a diff instead.
Code blocks are for "pre-formatted" text only. The only formatting you can get in a code block is the formatting that can be represented in plain text (indentation, capitalization, etc). There is no mechanism to mark up the content of a code block (as bold, italic, stricken, underlined, etc). This was an intentional design decision. Otherwise, how would you be able to show Markdown text in a code block? If you want formatted text, then you need to use something other than a code block.
As the rules state:
HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.
For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.
Therefore you would need to format your own custom HTML code block with the various bits marked up properly:
<pre><code><del>some stricken code</del>
<del>A second line of stricken code</del>
</code></pre>
However, for security reasons, GitHub will strip out any such raw HTML in your Markdown. So while this works where you have full control of the entire stack, on a hosted service it is most likely not possible.
However, I'm assuming you want to show some changes made to a block of code. As it turns out, a specific format already exists for that, namely, a diff. Just use a fenced code block with diff as the language and GitHub will format it correctly:
```diff
Unchanged Line
- Removed Line
+ Added Line
```
You can see how GitHub displays the above code block live (you can also see that in raw), but I've included a screenshot below for convenience.
I realize that the formatting does not use strike-through, but it does use a commonly used and understood format. For more complex blocks, you should probably use the diff utility program to generate the diff for you.
Expanding on Waylan's answer:
This may be obvious to others, but it caught me. When you have indented lines, be sure + or - is the first character on the line or it won't highlight.
```diff
<div>
Unchanged Line
<ul>
- <li>This won't work</li>
- <li>This will</li>
+ <li>1st character, then indent</li>
</ul>
</div>
```
After much much trying, I finally got it to work! It boils down to this:
inside ``` block, nothing is rendered (other than syntax highlights for language specified)
inside <code> block, markdown won't render, only HTML. You can use <strike>. It's fine, but you don't get the syntax coloring
now for the magic: use HTML for striking, and markdown for coloring:
<strike>
```language
this is
multiline code
```
</strike>
P.S. ``` blocks should always be surrounded by blank lines to work
On the subject of marking up the content of a code block, to tack an italicized string on to the end of a line of "code", try something like:
<code>id\_pn\_aside\_subscriber\_form\__form\_id_</code>
(You can see this in action at: https://github.com/devonostendorf/post-notif#how-do-you-use-the-stylesheet_filename-attribute-with-the-shortcode)
I had a hard time finding an example that matched this precise use case, so I hope this proves useful for anyone else trying to accomplish a similar effect.
I would like to emphasise several single letters at the beginning of a word to highlight the letters used for an abbreviation. Here's an example in markdown:
*SO* stands for *S*tack *O*verflow
But instead of the expected output (note the slanted first letters S and O) of:
SO stands for Stack Overflow
on Github the output looks like:
SO stands for *S*tack *O*verflow.
Any ideas why is it not emphasised on Github? Does this relate to the different markdown implementations?
Any ideas why is it not emphasised on Github?
This looks to be on purpose. This limit is hinted in their documentation.
Note: The documentation deals with underscores (_), which are similar to stars (*) in markdown
Indeed, the following is not processed by GitHub
*H*yper*t*ext *T*ransfer *P*rotocol
Does this relate to the different markdown implementations?
Well, at least it is documented. Keep in mind that is rightfully named "Github Flavoured Markdown" ;-)
Following this lead, I tried this in a Github README.md:
<span style="vertical-align: baseline; position: relative;top: -0.5em;>text in superscript</span>
Does not work, the text appears as normal. Help?
Use the <sup></sup>tag (<sub></sub> is the equivalent for subscripts). See this gist for an example.
You have a few options for this. The answer depends on exactly what you're trying to do, how readable you want the content to be when viewed as Markdown and where your content will be rendered:
HTML Tags
As others have said, <sup> and <sub> tags work well for arbitrary text. Embedding HTML in a Markdown document like this is well supported so this approach should work with most tools that render Markdown.
Personally, I find HTML impairs the readable of Markdown somewhat, when working with it "bare" (eg. in a text editor) but small tags like this aren't too bad.
LaTeX (New!)
As of May 2022, GitHub supports embedding LaTeX expressions in Markdown docs directly. This gives us new way to render arbitrary text as superscript or subscript in GitHub flavoured Markdown, and it works quite well.
LaTeX expressions are delineated by $$ for blocks or $ for inline expressions. In LaTeX you indicate superscript with the ^ and subscript with _. Curly braces ({ and }) can be used to group characters. You also need to escape spaces with a backslash. The GitHub implementation uses MathJax so see their docs for what else is possible.
You can use super or subscript for mathematical expressions that require it, eg:
$$e^{-\frac{t}{RC}}$$
Which renders as..
Or render arbitrary text as super or subscript inline, eg:
And so it was indeed: she was now only $_{ten\ inches\ high}$, and her face brightened up at the thought that she was now the right size for going through the little door into that lovely garden.
Which renders as..
I've put a few other examples here in a Gist.
Unicode
If the superscript (or subscript) you need is of a mathematical nature, Unicode may well have you covered.
I've compiled a list of all the Unicode super and subscript characters I could identify in this gist. Some of the more common/useful ones are:
⁰ SUPERSCRIPT ZERO (U+2070)
¹ SUPERSCRIPT ONE (U+00B9)
² SUPERSCRIPT TWO (U+00B2)
³ SUPERSCRIPT THREE (U+00B3)
ⁿ SUPERSCRIPT LATIN SMALL LETTER N (U+207F)
People also often reach for <sup> and <sub> tags in an attempt to render specific symbols like these:
™ TRADE MARK SIGN (U+2122)
® REGISTERED SIGN (U+00AE)
℠ SERVICE MARK (U+2120)
Assuming your editor supports Unicode, you can copy and paste the characters above directly into your document or find them in your systems emoji and symbols picker.
On MacOS, simultaneously press the Command ⌘ + Control + Space keys to open the emoji picker. You can browse or search, or click the small icon in the top right to open the more advanced Character Viewer.
On Windows, you can a emoji and symbol picker by pressing ⊞ Windows + ..
Alternatively, if you're putting these characters in an HTML document, you could use the hex values above in an HTML character escape. Eg, ² instead of ². This works with GitHub (and should work anywhere else your Markdown is rendered to HTML) but is less readable when presented as raw text.
Images
If your requirements are especially unusual, you can always just inline an image. The GitHub supported syntax is:
You can use a full path (eg. starting with https:// or http://) but it's often easier to use a relative path, which will load the image from the repo, relative to the Markdown document.
If you happen to know LaTeX (or want to learn it) you could do just about any text manipulation imaginable and render it to an image. Sites like Quicklatex make this quite easy. Of course, if you know your document will be rendered on GitHub, you can use the new (2022) embedded LaTeX syntax discussed earlier)
Comments about previous answers
The universal solution is using the HTML tag <sup>, as suggested in the main answer.
However, the idea behind Markdown is precisely to avoid the use of such tags:
The document should look nice as plain text, not only when rendered.
Another answer proposes using Unicode characters, which makes the document look nice as a plain text document but could reduce compatibility.
Finally, I would like to remember the simplest solution for some documents: the character ^.
Some Markdown implementation (e.g. MacDown in macOS) interprets the caret as an instruction for superscript.
Ex.
Sin^2 + Cos^2 = 1
Clearly, Stack Overflow does not interpret the caret as a superscript instruction. However, the text is comprehensible, and this is what really matters when using Markdown.
If you only need superscript numbers, you can use pure Unicode. It provides all numbers plus several additional characters as superscripts:
x⁰¹²³⁴⁵⁶⁷⁸⁹⁺⁻⁼⁽⁾ⁿⁱ
However, it might be that the chosen font does not support them, so be sure to check the rendered output.
In fact, there are even quite a few superscript letters, however, their intended use might not be for superscript, and font support might be even worse. Use your own judgement.
I am working on getting Japanese documents created with latex. I have installed the latest version of texlive-2008 which includes CJK.
In my document I have the following:
\documentclass{class}
\usepackage{CJK}
\begin{document}
\begin{CJK*}{UTF8}{min}
\title{[Japanese Characters here 1]}
\maketitle
\section{[Japanese Characters here 2]}
[Japanese Characters here 3]
\end{CJK*}
\end{document}
In the above code there are 3 locations Japanese characters are used.
1 + 3 work fine whereas 2, which contains Japanese characters in a \section{} fails with the following error.
! Argument of \#sect has an extra }.
After some research it turns out this error manifests when you’ve put a fragile command inside a moving argument. A moving argument because section can be moved to a contents page for example.
Does anyone know how to get this to work and why latex thinks Japanese characters are "fragile".
Sorry to post this as an answer rather than a comment to your answer; I don't have enough rep yet to comment. (EDIT: Now I have enough rep to comment, but I'm not sorry anymore. Thanks Will.)
Your solution of replacing
\section{[Japanese Text]}
with
\section{\texorpdfstring{[Japanese Text]}{}}
suggests that you're using the hyperref package. When you use the hyperref package, any sort of not-totally-boring text (e.g. math) within \section causes a problem because \section is having trouble generating pdf bookmarks. \texorpdfstring allows you to specify how you want the section title to appear in the pdf bookmark. For example, I might write
\section{Calculation of \texorpdfstring{$H_2(\mathcal{X})$}{H\_2(X)}}
if I want the section title to be "Calculation of $H_2(\mathcal{X})$" but I want the pdf bookmark to be "Calculation of H_2(X)".
You should probably use xetex/xelatex, as it has been created to support unicode. The change is sometimes not easy for already existing documents, though. (xelatex should be included in texlive, it is just different executable to call -- this is how it is done in Debian).
I have managed to get this working now!
Using Latex and CJK as before.
\section{[Japanese Text]}
was replaced with
\section{\texorpdfstring{[Japanese Text]}{}}
Now the contents pages and section titles work and update fine.