I get a weird output from my YAML header which I do not intend.
Instead I expect the normal output with title, author and the table of contents of course.
The following code produces the following output:
---
title: General Stuff
author: Me
output:
html_document:
toc: true # table of content true
toc_depth: 3 # upto three depths of headings (specified by #, ## and ###)
number_sections: true ## if you want number sections at each table header
theme: united
---
generates this output:
I got this output from GitHub where the file is displayed. Maybe the issue is that GitHub uses some interesting markdown version...?
Maybe the issue is that GitHub uses some interesting markdown version...?
YAML frontmatter isn't part of Markdown itself. A regular Markdown processor wouldn't do anything special with it. It would probably render a <hr> and some text, maybe ending with a header.
But yes, GitHub treats YAML front matter specially:
Many blogging websites, like Jekyll with GitHub Pages, depend on
some YAML-formatted metadata at the beginning of your post. You know, the stuff that goes between dashes like this:
---
title: Blogging Like a Boss
---
Starting [September 27, 2013], we’ll render this metadata within GitHub as an
horizontal table, for easier reading
Related
Back in the days GitHub Wiki supported embedding HTML tables, but now all our tables are not rendered anymore. Is support for HTML tables officially dropped (can't find corresponding news or blog post)?
GitHub does support table tag but it's not as extensible as in any HTML file. It's pretty much limited to what one may need for a wiki. In my view, it's pointless to use <table> because they are tiring compared to other markdowns that GitHub wiki use.
Markdown -
| First Header | Second Header |
| ------------- | ------------- |
| Content Cell | Content Cell |
| Content Cell | Content Cell |
Preview -
Equivalent HTML -
<table>
<tr><th>First Header</th><th>Second Header</th></tr>
<tr><td>Content Cell</td><td>Content Cell</td></tr>
<tr><td>Content Cell</td><td>Content Cell</td></tr>
</table>
PS. Here is a post on tables for markdown.
2017:
Back in the days GitHub Wiki supported embedding HTML tables, but now all our tables are not rendered anymore.
2022: they should be rendered now:
Updates to Markdown pasting on GitHub
May 19, 2022
We've made some updates to how paste formatting works in Markdown-enabled fields on GitHub.
For example, in code editors and on gists, you'll now be able to paste URLs on selected texts that will render as Markdown links like [...](https://...) by using the keyboard shortcut cmd|ctl + v..
The following paste formatting changes have been made to pull requests, issue comments and wikis:
Spreadsheet cells and HTML tables will render as Markdown tables
Any copied text containing links will render the links in Markdown.
All of this formatting can be disabled when pasting using the keyboard shortcut: cmd|ctl + shift + v or cmd|ctl + shift + Alt + v.
According to GitHub's Markdown spec, the Markdown parser permits most any raw HTML. The important thing is that the tags must begin at the start of the line. There are also rules which change the behavior when the raw block contains blank lines in some situations. Prior to adopting the current spec, I'm not sure if they were as strict about that, but that could be a reason for the change (some example input would help narrow down the possibilities).
And as another answer suggests, the GitHub Flavored Markdown spec includes a tables extension, so you can create tables natively in Markdown. This eliminates the need to structure your own HTML to the whims of the Markdown parser.
However, that is only the beginning of GitHub's processing of your input. After passing your input through the Markdown parser, there are four additional steps of processing taken on the output generated by Markdown as documented in the github/markup project. The most likely culprit is step two, which sanitizes the HTML. If your raw HTML doesn't match the expectations of the very narrow sanitizer, then it will get stripped out. The specifics of the santitizer are not documented, but the code is available to review and pretty easy to follow (even for those of use who aren't very familiar with Ruby).
Interestingly, the Markdown parser is sure to output HTML that the santitizer allows through, and in fact, tables are allowed. However, if you are using raw HTML rather than Markdown tables for more flexibility, then it is likely the extras that Markdown doesn't give you are causing the sanitizer to eat your tables (for example, you only get limited attributes, and improperly nests tags are stripped). In other words, raw HTML tables can only be limited to the basic features you already get with Markdown tables. Given the simplicity of Markdown tables over raw HTML, most people just use the markdown tables. YMMV.
What it looks like on MarkdownPad2 software:
What it looks like on GitHub:
There are numerous markdown engines and implementations, of which GitHub Flavored Markdown and MarkdownPad are just two. While they all implement markdown with basic similarities, there are always differences.
From looking at your screenshots, it seems the main issues lie with headings and code formatting.
For headings, try adding a space after the hash symbol:
# Foo
not
#Foo
For code blocks, try wrapping the code with three backticks:
```
Foo
```
In short, your best option is to read the GitHub markdown documentation and adjust your markdown text to fit with GitHub's formatting and syntax style.
You have multiple errors or not following some best practices:
Headings should have one space between # and the Heading text, e.g. # Heading
You should have empty line between paragraphs.
For code blocks, wrapping with triple back-ticks
Better to have only one top level header
Better to put empty lines around heading line to make your file easy to read.
You should get familiar with the Github Flavored Markdown (GFM) first. Suggest to read these links first Mastering Markdown and Markdown Cheatsheet
Tl;dr;
What is the correct way to create an anchor in docbook? and is there a way that will make the anchor visible in writer?
Background
I am trying to split up documentation that was previously in single open office documents into smaller asciidoc documents which are both included in the main open office document and also converted to either or both of html & pdf.
I have this mostly working. I use asciidoctor to create html. asciidoctor-pdf to create pdf and a combination of asciidoctor and pandoc to create .odt files. I also tried the python implementation of asciidoc but found the interface less useable.
Round tripping between asciidoc and odt is obviously not possible. This is sort of a fusion where the master document is word processed but pieces of content that can be produced independently (think man pages - in fact that is one of several use cases) are included.
asciidoc to html:
asciidoctor -b html5 foo.adoc -o foo.html
asciidoc to pdf:
asciidoctor-pdf -b pdf foo.adoc -o foo.pdf
asciidoc to odt
asciidoctor -b docbook foo.adoc -o foo.docbook
pandoc --base-header-level=3 -V date:"" -V title:"" -f docbook foo.docbook -o foo.odt
With pandoc I have to nullify the date and title and set the header-level as desired for the section to be inserted as an extra complication.
I insert the resulting .odt into the main document using insert section inside open office.
Note that the main document is not a master document as I could not find a way of creating a master document without also automatically splitting the file on h1 boundaries.
I have two main problems to resolve with this set-up. I would like to add headings in the asciidoc document as cross references and also create entries for them in the alphabetical index (actually the first heading would be suffcient). Is there a way to do this?
Index markers in asciidoc do not result in entries in .odt file being created.
I am able to cross reference content in the inserted section using "insert reference/heading" and referencing the uniquely named header. However, whenever I use "update all" these cross references are invalidated. They are shown as "Error: Reference source not found".
[On a separate note I would also like a way to find broken cross references automatically]
I am currently using libreoffice - Version: 4.3.7.2
I am not adverse to switching version or flavours (i.e. apache) if one behaves better than the other.
I'm not sure if the answer is in the asciidoc or docbook parts of the chain. I would accept an answer which inserts a index entry at the start of the inserted section (top of the .adoc/docbook file) automatically.
I am also open to changing my toolchain to something that will work.
For example I tried the asciidoc-odt backend and fell foul of https://github.com/dagwieers/asciidoc-odf/issues/47 which does not inspire confidence.
Using asciidoc-odt I avoid the need to create an intermediate docbook file. However, I still can't get the anchor to appear.
I can get a macro to create an anchor but at present I haven't figured out how to run the macro from the command line.
To create an anchor in DocBook, make an inline anchor in the .adoc file. For example, giving this to asciidoctor:
[[X1]]Section1
---------------
produced this:
<title>
<anchor xml:id="X1" xreflabel="[X1]"/>
Section1
</title>
Conversely, putting this on separate lines did not create an anchor tag in my test:
[[X1]]
Section 1
Now for some bad news. From the Pandoc User's Guide:
Internal links are currently supported for HTML formats (including HTML slide shows and EPUB), LaTeX, and ConTeXt.
I interpret this to mean that currently, Pandoc does not create internal links in Writer. When I tried it, the link was ignored.
Note: It looks like I did not answer all of your questions. If you want to ask more about LibreOffice cross references and headings (the big bold paragraph towards the end of the question), maybe you could make a separate question just for that part.
I have an .rmd file that I want to put on GitHub. In order for the results to be visible along with the code I converted my .rmd file to .md via RStudio.
After conversion, however, the (r-)code is not highlighted anymore, when I view the .md file on GitHub. I noticed that a code block in the .md file is identified by indending 4 times instead of three backticks + language definition. So obviously the language definition from the .rmd file gets lost.
How can I fix this?
Note: To reproduce you can just open a new .rmd file in RStudio and change the YAML header to:
---
title: "TestRun"
output:
md_document:
variant: markdown_github
---
Help is much appreciated!
Indentation is important in YAML.
Here's an example from the R Markdown documentation:
---
output:
md_document:
variant: markdown_github
---
This YAML document has a mapping with the key output, whose value is a mapping with one key, md_document, whose value is a mapping with one key, variant, whose value is the scalar markdown_github.
The equivalent in JSON (for example) would be:
{ "output": {
"md_document": {
"variant": "markdown_github"
}
}
}
Here's your document (disregarding the title key for clarity):
---
output:
md_document:
variant: markdown_github
---
Your document has a mapping with the key output, whose value is a mapping with two keys, md_document (with an empty or null value) and variant (with the scalar value markdown_github). The JSON equivalent would be:
{ "output": {
"md_document": null,
"variant": "markdown_github"
}
}
See the difference?
Fenced code blocks (backticks + language definition) is a non-standard (although increasingly common) way of marking up code blocks. Therefore, it is not understood by all Markdown implementations. In fact, standard Markdown offers no way to identify the language of a code block. That being the case, when converting to standard Markdown, that info is appropriately lost. If you would like to retain that info, then I would suggest converting to something other that standard Markdown. Although, according to another answer, if you fix your YAML config, then you would be using the non-standard GitHub Flavored Markdown, which does support fenced code blocks.
If you really need standard Markdown, then you may find that a JavaScript highlighting engine will serve you fine. Some of the better JavaScript highlighting engines have pretty good language detection, so you usually don't need to label the language of the code blocks.
I can find no way to insert syntactically acceptable RStudio style folds into an external R code file that is set up for use from a knitr document. Or am I missing something. There are several ways this might be done:
1) Allow a code header such as:
## #knitr Q1 ----
or perhaps
## #knitr 'Q1' ----
2) Fold every code chunk (this would be a change in RStudio), but this is not as
general as I would ideally like.
3) Allow the inclusion of some kind of comment line in code files that would indicate a fold. I have not been able to find a way to do this that does not add the comment line to the previous code chunk.
[Since initially posting this, I have noticed that the arguments 'from' and 'to' in read_chunk() can be regular expressions that specify start and from character strings for code chunks. So this gives one way to allow the insertion of comment lines that can specify folds. It would be nice however to be able to use one or more of mechanisms 1-3 above.]
From knitr v1.2.11 and above, the RStudio style code headers are supported consistently in knitr. The rule is basically # ---- label:
one or more hashes # in the beginning
followed by at least four dashes ----
followed by the chunk label
and optionally followed by any number of dashes
This is supported in both read_chunk() and purl(), i.e., this style of comments is used in both importing and exporting code in knitr.
For RStudio to support code-folding, however, you will have to add at least four dashes to the end of the comment header, e.g.,
# ---- chunk-label -----------------------------
knitr 1.2.11 is a development version on Github, which will become 1.3 eventually on CRAN.