Is there an elegant way how to include table from an external file in markdown document rendered by GitHub?
Non elegant solutions I can think of:
include it as image (this one is really really ugly)
use Rmarkdown and print table using R (wont be rendered by default)
Just to give a bit of explanation. I am using a set of README.md files in my git repository (hosted by GitHub), so it is really clear to browse repo online, because GitHub renders automatically README.md file in every subdirectory.
I am algorithmically generating summary tables that should be included in those documents. It would be way more elegant if that table could be read from external file, because I do not want to write scripts that will modify README.md files directly.
There is no way to include files within markdown. So you need a "preprocessing" stage to generate the markdown which is then shown on Github (or rendered with normal markdown tools).
What Github supports is a basic table layout, which you'd need to render:
Solution 1: scripting
You could add something like this to your README.md:
<!-- TABLE_GENERATE_START -->
| First Header | Second Header |
| ------------- | ------------- |
| Content Cell | Content Cell |
| Content Cell | Content Cell |
<!-- TABLE_GENERATE_END -->
And then have a script which pulls in the external table, reformats it to match the github format and puts it between the two comment.
Solution 2: pandoc
Pandoc is a document converter framework with many possible inputs and outputs. If you're up to learn another tool you could
reformat you table into a markdown file using csv2table into table.md
create a readme_header.md and readme_footer.md with the markdown before/after the table
merge the three files with cat readme_header.md table.md readme_footer.md > REAME.md
Of course you can also do a mixture of both solutions, e.g. generate table.md using a script and merge using cat
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 am playing with Tal's intro to producing word tables with as little overhead as possible in real world situations. (Please see for reproducible examples there - Thanks, Tal!) In real application, tables are to wide to print them on a portrait-oriented page, but you might not want to split them.
Sorry if I have overlooked this in the pandoc or pander documentation, but how do I control page orientation (portrait/landscape) when writing from R to a Word .docx file?
I maybe should add tat I started using knitr+markdown, and I am not yet familiar with LaTex syntax. But I'm trying to pick up as much as possible while getting my stuff done.
I am pretty sure the docx writer has no section breaks implemented, also as far as I understand --reference-docx allows for customizing styles and not the page layout (but I might also be wrong here), this is from pandocs guide on --reference-docx:
--reference-docx=FILE
Use the specified file as a style reference in producing a docx file.
For best results, the reference docx should be a modified version of a
docx file produced using pandoc. The contents of the reference docx
are ignored, but its stylesheets are used in the new docx. If no
reference docx is specified on the command line, pandoc will look for
a file reference.docx in the user data directory (see --data-dir). If
this is not found either, sensible defaults will be used. The
following styles are used by pandoc: [paragraph] Normal, Title,
Authors, Date, Heading 1, Heading 2, Heading 3, Heading 4, Heading 5,
Block Quote, Definition Term, Definition, Body Text, Table Caption,
Image Caption; [character] Default Paragraph Font, Body Text Char,
Verbatim Char, Footnote Ref, Link.
Which are styles that are saved in the /word/styles.xml component of the docx document.
The page layout on the other hand is saved in the /word/document.xml component in the <w:sectPr> tag, but pandoc's docx writer ignores this part as far as I can tell.
The docx writer builds by default a continuous document, with elements such as headers, paragraphs, simple tables and so on ... much like a html output.
Option #1 (doesn't solve the page orientation problem):
The only page layout option that you can define through styles is the pageBreakBefore which will add a page break before a certain style
Option #2 (seems elegant but hasn't been tested):
Recently the custom writer has been added that allows for a custom lua script, where you should be able to define how certain Pandoc blocks will be written into the output file ... meaning you could potentially define section breaks and page layout for a specific block inserting the sectPr tag into the document. I haven't tried this out but it would be worth investigating. On pandoc github you can check out a sample lua script file for custom html output.
However, this means, you have to have lua installed, learn the language, and it is up to you if you think its worth the time investment.
Optin #3 (a couple of clicks in Word might just do):
As you will probably spend quite some time setting up how to insert sections and what would be the right size, margins, and figuring how to fit the table to such a layout ... I recommend that you use pandoc to put write your document.docx, that you open in Word, and do the layout by hand:
select the table you want on the landscape page
go to Layout > Margins
> select Apply to: Selected text
> choose Page Setup > select Landscape
Now a new section with a landscape orientation should surround your table.
What you would anyway also probably want to do is styling the table and table caption a little (font-size,...), to achieve the best result (all text styling can be already applied with pandoc where --reference-docx comes handy).
Option #4 (in situation when you can just use pdf instead of docx):
As far as I could figure out is that with pandoc does a good job with tables in md -> docx (alignment, style, ... ), in tex -> docx it had some trouble sometimes. However if your option allows for a pdf output latex will be your greatest friend. For example your problem is solved as easily as just using
\usepackage{pdflscape}
and adding this around your table
\begin{landscape}
...
\end{landscape}
This are the options that I could think of so far.
I would always recommend using the pdf format for reports, as you can style it to your liking with latex and the layout will stay the way you want it to be.
However, I also know that for various reasons word documents are still the main way of reviewing manuscripts in many fields ... so i would most likely just go with my suggested option 3, mostly cause it is a lazy and quick solution and because I usually don't have many documents with tons of giant tables with awkward placement and styling.
Good luck ;-)
Based on Taleb's answer here and some officer package functions, I created a little gist that one can use like this:
---
title: "Example"
author: "Dan Chaltiel"
output:
word_document:
pandoc_args:
'--lua-filter=page-break.lua'
---
I'm in portrait
\endLandscape
I'm in landscape
\endPortrait
I'm in portrait again
With page-breaks.lua being the file hosted here: https://gist.github.com/DanChaltiel/e7505e62341093cfdc489265963b6c8f
This is far from perfect (for instance it won't work without the last portrait section), but it is quite useful sometimes.
After investigating, I've found mathjax can do this. But when I write some example in my markdown file, it doesn't show the correct equations:
I have added this in the head of markdown file:
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=default"></script>
And type the mathjax statement:
\(E=mc^2\)，$$x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}.$$
But github shows nothing for the math symbols! Please help me, thanks!
Tell me how to show math symbols in github markdown pages.
But github show nothing for the math symbols! please help me, thanks!
GitHub markdown parsing is performed by the SunDown (ex libUpSkirt) library.
The motto of the library is "Standards compliant, fast, secure markdown processing library in C". The important word being "secure" there, considering your question :).
Indeed, allowing javascript to be executed would be a bit off of the MarkDown standard text-to-HTML contract.
Moreover, everything that looks like a HTML tag is either escaped or stripped out.
Tell me how to show math symbols in general github markdown.
Your best bet would be to find a website similar to yuml.me which can generate on-the-fly images from by parsing the provided URL querystring.
Update
I've found some sites providing users with such service: codedogs.com (no longer seems to support embedding) or iTex2Img.
You may want to try them out. Of course, others may exist and some Google-fu will help you find them.
given the following markdown syntax
it will display the following image
Note: In order for the image to be properly displayed, you'll have to ensure the querystring part of the url is percent encoded. You can easily find online tools to help you with that task, such as www.url-encode-decode.com
Markdown supports inline HTML. Inline HTML can be used for both quick and simple inline equations and, with and external tool, more complex rendering.
Quick and Simple Inline
For quick and simple inline items use HTML ampersand entity codes. An example that combines this idea with subscript text in markdown is: hθ(x) = θo x + θ1x, the code for which follows.
h<sub>θ</sub>(x) = θ<sub>o</sub> x + θ<sub>1</sub>x
HTML ampersand entity codes for common math symbols can be found here. Codes for Greek letters here. An extensive list html entity codes to Unicode characters can be found here.
While this approach has limitations it works in practically all markdown and does not require any external libraries.
Complex Scalable Inline Rendering with LaTeX and Codecogs
If your needs are greater use an external LaTeX renderer like CodeCogs. Create an equation with CodeCogs editor. Choose svg for rendering and HTML for the embed code. Svg renders well on resize. HTML allows LaTeX to be easily read when you are looking at the source. Copy the embed code from the bottom of the page and paste it into your markdown.
<img src="https://latex.codecogs.com/svg.latex?\Large&space;x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}" title="\Large x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}" />
Expressed in markdown becomes
This combines this answer and this answer.
GitHub support only somtimes worked using the above raw html syntax for readable LaTeX for me. If the above does not work for you another option is to instead choose URL Encoded rendering and use that output to manually create a link like:
This manually incorporates LaTex in the alt image text and uses an encoded URL for rendering on GitHub.
Multi-line Rendering
If you need multi-line rendering check out this answer.
It ’s 2020 now, let me summarize the progress of the mathematical formula rendering support of source code repository hosts.
GitHub & Bitbucket
GitHub and Bitbucket still do not support the rendering of mathematical formulas, whether it is the default delimiters or other.
Bitbucket Cloud / BCLOUD-11192 -- Add LaTeX Support in MarkDown Documents (BB-12552)
GitHub / markup -- Rendering math equations
GitHub / markup -- Support latex
GitHub Community Forum -- [FEATURE REQUEST] LaTeX Math in Markdown
talk.commonmark.org -- Can math formula added to the markdown
GitHub has hardly made any substantial progress in recent years.
GitLab
GitLab is already supported, but not the most common way. It uses its own delimiter.
This math is inline $`a^2+b^2=c^2`$.
This is on a separate line
```math
a^2+b^2=c^2
```
GitLab Flavored Markdown -- Math
Who supports the universal delimiters?
A Markdown parser used by Hugo
Other ways to render
Use web api to render according to A hack for showing LaTeX formulas in GitHub markdown, you can even write jupyter notebook.
readme2tex
It is officially supported since May 2022:
Render mathematical expressions in Markdown
You can now use LaTeX style syntax to render math expressions within Markdown inline (using $ delimiters) or in blocks (using $$ delimiters).
Writing expressions as blocks
To add math as a multiline block displayed separately from surrounding text, start a new line and delimit the expression with two dollar symbols $$.
**The Cauchy-Schwarz Inequality**
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
Writing inline expressions
To include a math expression inline with your text, delimit the expression with a dollar symbol $.
This sentence uses `$` delimiters to show math inline: $\sqrt{3x-1}+(1+x)^2$
GitHub's math rendering capability uses MathJax; an open source, JavaScript-based display engine.
MathJax supports a wide range of LaTeX macros and a number of useful accessibility extensions.
For more information, see the MathJax documentation and the MathJax Accessibility Extensions documentation.
Some users have previously used a workaround to generate images of mathematical expressions through API requests.
Images generated this way will remain viewable, but this technique will no longer work.
Going forward, expressions should be written directly in Markdown using LaTeX syntax as described above.
For more information about authoring content with advanced formatting, see Working with advanced formatting in the GitHub documentation.
This is still beta, and criticised.
See "Math on GitHub: The Good, the Bad and the Ugly" from Nico Schlömer.
The syntax introduces:
Competing Markdown and math renderer
A math block hard to interpret
As noted by brc-dd in the comments:
June 2022:
Fenced block syntax for mathematical expressions
Users can now delineate mathematical expressions using ```math fenced code block syntax in addition to the already supported delimiters.
Two dollar sign $$ delimiters are not required if this method is used.
**Here is some math!**
```math
\sqrt{3}
.```
becomes:
Read more about working with advanced formatting.
Another possibility is to rely on GitHub's own notebook renderer. This even works right here in SO.
To render x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b} use the following HTML img tag:
<img src="https://render.githubusercontent.com/render/math?math=x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}">
Live Demo:
What's great about this approach is that you can edit your formula directly in Markdown and the preview will update accordingly.
You can try it out by editing this answer. (Just throw away your edits if they don't add to the answer ;))
Source: https://gist.github.com/a-rodin/fef3f543412d6e1ec5b6cf55bf197d7b
One other work-around is to use jupyter notebooks and use the markdown mode in cells to render equations.
Basic stuff seems to work perfectly, like centered equations
\begin{equation}
...
\end{equation}
or inline equations
$ \sum_{\forall i}{x_i^{2}} $
Although, one of the functions that I really wanted did not render at all in github was \mbox{}, which was a bummer. But, all in all this has been the most successful way of rendering equations on github.
If just wanted to show math in the browser for yourself, you could try the Chrome extension GitHub with MathJax. It's quite convenient.
While GitHub won't interpret the MathJax formulas, you can automatically generate a new Markdown document with the formulae replaced by images.
I suggest you look at the GitHub app TeXify:
GitHub App that looks in your pushes for files with extension *.tex.md and renders it's TeX expressions as SVG images
How it works (from the source repository):
Whenever you push TeXify will run and seach for *.tex.md files in your last commit. For each one of those it'll run readme2tex which will take LaTeX expressions enclosed between dollar signs, convert it to plain SVG images, and then save the output into a .md extension file (That means that a file named README.tex.md will be processed and the output will be saved as README.md). After that, the output file and the new SVG images are then commited and pushed back to your repo.
I use the below mentioned process to convert equations to markdown. This works very well for me. Its very simple!!
Let's say, I want to represent matrix multiplication equation
Step 1:
Get the script for your formulae from here - https://csrgxtu.github.io/2015/03/20/Writing-Mathematic-Fomulars-in-Markdown/
My example: I wanted to represent Z(i,j)=X(i,k) * Y(k, j); k=1 to n into a summation formulae.
Referencing the website, the script needed was => Z_i_j=\sum_{k=1}^{10} X_i_k * Y_k_j
Step 2:
Use URL encoder - https://www.urlencoder.org/ to convert the script to a valid url
My example:
Step 3:
Use this website to generate the image by copy-pasting the output from Step 2 in the "eq" request parameter - http://www.sciweavers.org/tex2img.php?eq=<b><i>paste-output-here</i></b>&bc=White&fc=Black&im=jpg&fs=12&ff=arev&edit=
- My example:
http://www.sciweavers.org/tex2img.php?eq=Z_i_j=\sum_{k=1}^{10}%20X_i_k%20*%20Y_k_j&bc=White&fc=Black&im=jpg&fs=12&ff=arev&edit=
Step 4:
Reference image using markdown syntax - 
- Copy this in your markdown and you are good to go:
Image below is the output of markdown. Hurray!!
I just released a little Chrome extension, xhub, that lets you use LaTeX math (and more) in GitHub pages.
Pros:
You don't have to set up anything in your repo, just use math in your Markdown (sytax from GitLab):
Some display math:
```math
e^{i\pi} + 1 = 0
```
and some inline math, $`a^2 + b^2 = c^2`$.
It works on light and dark backgrounds alike.
You can copy-and-paste the math
Cons:
You have to install a browser extension once.
There is good solution for your problem - use TeXify github plugin (mentioned by Tom Hale answer - but I developed his answer in given link below) - more details about this github plugin and explanation why this is good approach you can find in that answer.
I used the following in the head of mark down file
<script type="text/javascript" async
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?
config=TeX-MML-AM_CHTML"
</script>
Then typed the following mathjax statement
$$x_{1,2} = \frac{-b \pm \sqrt{b^2-4ac}}{2b}.$$
It worked for me
A "quick and dirty" solution is to maintain a standard .md file using standard TeX equations, e.g. _README.md.
When you are satisfied, pass the entire file through Pandoc to convert from standard Markdown to Markdown (Github flavour), and copy the output to README.md.
You can do this online for a quick turnaround, or install/configure Pandoc locally.
Mathcha is a sophisticated mathematics editor, but it can be used to render individual equations and save them as pure html, which you can then add to your documents as inline html OR you can save as SVG and insert as an image. https://www.mathcha.io/
You can embed your LaTeX in an image URL rendered by render.githubusercontent.com such as this one:
<img src="https://render.githubusercontent.com/render/math?math={x + y}">
which will render like this:
Which you'll notice is missing the + sign. To fix that you can URL encode the plus sigh as %2b or URL encode the entire equation, which will render like so:
Unfortunately this will always render in black, so you'll want to use this GitHub specific trick to render white text for users using dark mode and black text to users using light mode, by including the equation once with the #gh-light-mode-only and again with the LaTeX comand \color{white} and the #gh-dark-mode-only tag:
<img src="https://render.githubusercontent.com/render/math?math={x - y}#gh-light-mode-only">
<img src="https://render.githubusercontent.com/render/math?math={\color{white}x - y}#gh-dark-mode-only">
which will display this to light mode users:
and display this to dark mode users:
Now since May 2022, Github accept LATEX directly into Markdown, the only thing to do is to put the LATEX code inside $$$$ on your markdown
One more thing, you can colorize the math using the {\color{nameColor}text} on markdown
$${\color{red}\sum\limits_{\color{lightblue}i=0}^{\color{orange}n} {\color{pink}i}} = \frac{\color{pink}n!}{\color{lightblue}k!(n-k)!}$$
Example in a picture:
$$\sum\limits_{i=0}^n i^2$$ create the sum:
Regarding tex→image conversion, the tool LaTeXiT produces much higher quality output. I believe it is standard in most TeX distributions but you can certainly find it online if you don't already have it. All you need to do is put it in the TeX, drag the image to your desktop, then drag from your desktop to an image hosting site (I use imgur).
TeXify is no longer working. Check my repo readme2tex-action on how to create Github actions.
Add action.yml file to your repo at .github/workflows/action.yml.
Change branch main name if it is necessary.