I understand that cramdown does not support \newcommand type macros.
Is there a workaround that does not involve Pandoc, so that it could be used with Jekyll in a GitHub blog?
This would be the input markdown:
---
layout: post
---
\newcommand{\a}{\alpha}
This is a test $$\a$$.
The output should be a Jekyll blog, with mathematical notation, like this.
There seems to be two questions here — first, can one define commands in kramdown similar to LaTeX's \newcommand syntax, and second, can kramdown support mathematics.
Regarding the first issue, kramdown itself doesn't support that syntax or anything like it that I'm aware of, and probably isn't going to in the future, so you can't define non-math kramdown commands. You'd need to use a language that's focused on completeness rather than ease and simplicity, like LaTeX, to get features like that.
For math, though, MathJax (the parser kramdown uses) does parse \newcommand: just go ahead and use it in the first code block. So for example,
$$\newcommand{\a}{\alpha} \a{}/2 $$
yields the expected fraction with the expected Computer Modern italic Greek alpha, and you'll also be able to use \a in every subsequent code block. You can also have a code block at the beginning of your document that contains all of your \newcommand definitions if you don't want them to be interspersed in random code blocks throughout your document.
Regarding the second issue, as I guess is obvious at this point, kramdown does handle math using similar notation to LaTeX:
Here is a paragraph with some inline math, $$ \pi{}/2 $$, followed by
some text and a math block.
$$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$
This yields:
<p>Here is a paragraph with some inline math, <script
type="math/tex">\pi{}/2</script>, followed by some text and a math
block.</p>
<script type="math/tex; mode=display">\int_{-\infty}^{\infty} e^{-x^2}
dx = \sqrt{\pi}</script>
If that isn't successfully rendering for you on your site, don't forget to include the MathJax library in the <head> of your HTML page:
<script type="text/javascript"
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
Related
Has anyone documented the differences between Stack Exchange Markup and Github Markup?
I'm in the midst of a project to convert Stack Exchange Markdown to Github Markdown. It might be a little more complicated because Jekyll on Github Pages uses a Markdown derivative called "Kramdown".
I've already written some of the conversion in my Python program. For example old SE posts with #Header must be converted to # Header.
Another example are "> Block quote" lines have two spaces appended to the end of the line.
Now it's starting to get tricky (for me at least) where in an image in SE is specified as:
[![Ubuntu 5 DE.png][1]][1]
**Note:** Blah, blah, blah
[1]: https://i.stack.imgur.com/MoxHd.jpg
It has to be converted to Github image markdown format:
**Note:** Blah, blah, blah
Another example of "footer hyper links" (for lack of a better noun) in Stack Exchange Markdown is:
- [Jack Master Volume?][1]
The simplest solution then is to install [JackMix][2]:
find listed [here][3].
[this script][4] is where you are heading:
[1]: https://discourse.ardour.org/t/jack-master-volume/84650
[2]: http://www.arnoldarts.de/jackmix/.
[3]: http://jackaudio.org/applications/
[4]: https://unix.stackexchange.com/questions/374085/lower-or-increase-pulseaudio-volume-on-all-outputs
Needs to be converted to Github Markdown format of:
- [Jack Master Volume?](https://discourse.ardour.org/t/jack-master-volume/84650)
The simplest solution then is to install [JackMix](http://www.arnoldarts.de/jackmix/.):
find listed [here](http://jackaudio.org/applications/).
[this script](https://unix.stackexchange.com/questions/374085/lower-or-increase-pulseaudio-volume-on-all-outputs) is where you are heading:
Finally tonight I discovered that in Stack Exchange you can have:
<!-- language: bash -->
#!/bin/bash
cat "$Filename.zip" | base64 > "$Filename64"
That needs reformatting to Github Markdown like this:
``` bash
#!/bin/bash
cat "$Filename.zip" | base64 > "$Filename64"
```
It gets even more complicated when SE Markdown has:
<!-- language-all: lang-bash -->
Or it has this:
<pre><code>Some lines of code
some more lines of
code </code></pre>
An existing Github Repo to convert would be awesome! If not then if someone has documented the differences between Stack Exchange Markup and Github Markup that would be great too.
If this question goes unanswered for a month then I guess I'll be answering it eventually after the trial-error-fix process is finished.
The self-answer seems to answer a different question, so I'll answer the one posed above.
Has anyone documented the differences between Stack Exchange Markup and Github Markup?
As of mid-2020, Stack Exchange uses CommonMark with support for a few custom features "like spoilers, MathJax, circuit diagrams, stack snippets, etc."
GitHub uses their own dialect, GitHub Flavored Markdown (GFM). The most notable extensions that GFM introduces are probably tables (supported on SE since late 2020), fenced code blocks (supported on SE since early 2019), and task lists (unsupported but also not really necessary on SE).
Most of the examples shown above work fine when rendered on Stack Exchange or by a compliant GFM implementation, but let's look at them in turn:
For example old SE posts with #Header must be converted to # Header.
This should have been cleaned up by the migration to CommonMark:
we will run a big migration across the network that will convert existing posts to use the new CommonMark format
Another example are "> Block quote" lines have two spaces appended to the end of the line.
Two spaces at the end of the line indicate a line break in Markdown, going all the way back to the original implementation.
Blockquotes do not require such line breaks, though they will rewrap without them. Line breaks and blockquotes are unrelated features.
Your image examples are interchangeable in both formats. Let's look at the SE one:
[![Ubuntu 5 DE.png][1]][1]
**Note:** Blah, blah, blah
[1]: https://i.stack.imgur.com/MoxHd.jpg
There is nothing specific to Stack Exchange here.
The [foo][1]… [1]: https://... syntax is a reference-style link which, again, comes from the original project. It is equivalent to the inline form [foo](https://...). Both forms work on both platforms. ![Ubuntu 5 DE.png][1]… [1]: https://i.stack.imgur.com/MoxHd.jpg is the same as .
On SE images are wrapped by a link by default, which introduces the wrapping [...][1]. But, again, this is not SE-specific. It's like comparing <img src="..."> to <img src="...">. This also works on both platforms.
Another example of "footer hyper links" (for lack of a better noun)
These are reference-style links already discussed and present in every version of Markdown I've ever seen, including the original project. They work in GFM as well as they do in CommonMark. No conversion is necessary.
Finally tonight I discovered that in Stack Exchange you can have:
<!-- language: bash -->
#!/bin/bash
cat "$Filename.zip" | base64 > "$Filename64"
That needs reformatting to Github Markdown like this:
``` bash
#!/bin/bash cat "$Filename.zip" | base64 > "$Filename64"
```
This is the only example above that requires any special behaviour at all. However, it mostly works out of the box. GFM supports indented code blocks and SE has supported fenced code blocks for over three years.
GFM doesn't understand legacy HTML-style SE language hints <!-- language: bash --> and <!-- language-all: ... -->, so it will render such code blocks without syntax highlighting. But they will still render as a code block.
The last example is just embedded HTML that both platforms (and the original) know how to render:
<pre><code>Some lines of code
some more lines of
code </code></pre>
With the exception of HTML-style language hints, every example you show above works out of the box on both Stack Exchange and GitHub Flavored Markdown. No conversion necessary.
Converting thousands of Stack Exchange Q&A in markdown format isn't as easy
as simply copying them over to GitHub Pages. The python program
stack-to-blog.py was used to convert Stack Exchange posts to
GitHub Pages Posts.
The full stack-to-blog.py program can be accessed on the
Pippim Website repo 🔗.
The program automatically:
Creates Jekyll front matter on posts and front matter totals for site.
Selects Stack Exchange Posts based on meeting minimum criteria such as up-votes or accepted answer status.
If self-answered question, the answer is included and not the question.
If self-answered question, the accepted answer alone doesn't qualify. Votes from other are the qualifier.
Initial testing allows selecting small set of random record numbers to convert.
Converts Stack Exchange Markdown formats to GitHub Pages Kramdown Markdown format.
Creates hyperlinks to original Answer in Stack Exchange and Kramdown in GitHub Pages.
Creates search word to URL indices excluding 50% of words like "a", "the", etc. to save space.
Selectively inserts Table of Contents based on minimum criteria settings.
Selectively inserts Section Navigation Buttons for: Top (Top of Page), ToS (Top of Section), ToC (Table of Contents) and Skip (Skip section).
Selectively inserts "Copy Code Block to System Clipboard" button based on lines of code.
Creates HTML with "Top Ten Answers" with the most votes.
Creates powerful nested expandable/collapsible detail/summary HTML for many thousands of tags by post.
Remaps hyperlinks in Stack Exchange Posts to {{ site.title }} website posts if they were converted.
Fixes old broken #header Stack Exchange Markdown.
Converts < block quote Stack Exchange Markdown into what works in Jekyll Kramdown.
Convert Stack Exchange <!-- language --> tags to fenced code block language.
When no fenced code block language is provided, uses shebang language first (if available).
Converts older four-space indented code blocks to fenced code blocks.
Converts Stack Exchange Hyperlinks where the website post title is implied and not explicit.
Prints list of self-answered questions that were not accepted after the mandatory two day wait period.
Prints list of Rouge Syntax Highlighting languages not supported in fenced code blocks.
Prints summary totals when finished.
Full documentation is provided here.
This is what program looks like when running:
I have already seen some other links related to this question, which are mentioned as below:
How to write LaTeX in IPython Notebook?
https://towardsdatascience.com/write-markdown-latex-in-the-jupyter-notebook-10985edb91fd
https://colab.research.google.com/drive/18_2yFdH8G-6NXY_7fTcshMoScgJ-SYac#scrollTo=go3imAWqE9au
However, I am still facing some problems while using the Latex code inside Jupyter notebook.
For example,
\begin{align*}
f(x) &= x^2\\
g(x) &= \frac{1}{x}\\
F(x) &= \int^a_b \frac{1}{3}x^3
\end{align*}
This works fine as Markdown but
\begin{equation*}
f(x) &= x^2\\
g(x) &= \frac{1}{x}\\
F(x) &= \int^a_b \frac{1}{3}x^3
\end{equation*}
does not.
While trying to create an ordered list using the following
\begin{enumerate}
\item The labels consists of sequential numbers.
\item The numbers starts at 1 with every call to the enumerate environment.
\end{enumerate}
However, $\textbf{This is a bold text.}$ works.
It's really confusing what I can use and whatnot. Is there any way so that I can use only Latex code (and no HTML or other code) inside Visual Studio code to format my texts and equations without worrying about which will work and which not?
The short and very pragmatic answer is: you can't.
When you type something like $ a^2 $ in a markdown cell, what Jupyter Notebook actually does is send it to a library called MathJax. Mathjax, in its turn, does not compile the TeX code you typed using a standard LaTeX compiler. It, instead, just looks for mathematics environments and try to process the TeX-like syntax into something MathJax can understand.
Diving in LaTeX-stuff
There are two modes in (La)TeX: the text mode and the math mode, which are treated separately by the TeX compiler. For example, open your TeX editor and try to compile the following code.
\documentclass{article}
\begin{document}
a^2
$ ação $
\end{document}
You'll receive that error:
! Missing $ inserted.
<inserted text>
$
l.4
I've inserted a begin-math/end-math symbol since I think
you left one out. Proceed, with fingers crossed.
Missing character: There is no ç (U+00E7) in font cmmi10!
Missing character: There is no ç (U+00E7) in font cmmi10!
Missing character: There is no ã (U+00E3) in font cmmi10!
Missing character: There is no ã (U+00E3) in font cmmi10!
It's telling you that (1) you can't use ^ in text mode; (2) you can't use unicode characters such as ç and ã in math mode.
At this point, it's important to remember that align environments are courtesy of amsmath or mathtools packages, and doesn't exists in "plain" LaTeX
Back to MathJax
Unlike a real LaTeX compiler, MathJax does not implement the entire TeX macros universe, but only those related to the math mode (as the name suggests). From documentation:
Note that the TeX input processor implements only the math-mode macros of TeX and LaTeX, not the text-mode macros. MathJax expects that you will use standard HTML tags to handle formatting the text of your page; it only handles the mathematics. So, for example, MathJax does not implement \emph or \begin{enumerate}...\end{enumerate} or other text-mode macros or environments. You must use HTML to handle such formatting tasks. If you need a LaTeX-to-HTML converter, you should consider other options.
However, there are some exceptions. The default configuration of TeX input processor allow detecting environments outside math mode, so those environment related to math (equation, align, matrix, etc) can be correctly typeset. Recall that LaTeX does not implements align out-of-the-box, while MathJax does.
And what about the buggy equation environment?
Regarding your buggy equation environment, it's more a LaTeX stuff. equation environments does not support line breaks (\\) neither & (the first one I can't explain exactly why, but certainly someone in TeX SE can), so your input is invalid.
You can now with the latest version of VS Code. The feature is still in preview (as of writing) so you have to enable it in settings.json by adding "notebook.experimental.useMarkdownRenderer": true
Restart VS Code and try $$y=x^2$$ and press ctrl+enter to see it rendered. I think for now the equation needs to be on a separate line by itself.
Here's the announcement: https://code.visualstudio.com/updates/v1_55#_preview-features
The publish function in MATLAB works for both scripts and functions,
while the one for Octave works only for scripts: if I enter
publish myFunc.m
Octave gave
error: publish: Only Octave script files can be published.
Am I able to publish a function in Octave? If yes, how?
You can use Octave Forge generate_html package which is meant to generate html of individual functions. It is mostly used to generate the documentation of Octave Forge packages, and its defaults reflect that, but you could add any style you want.
This package will use the same help text that the help function in Octave sees which is the first block of comments in the file that does not start by Copyright or Author. You can have it in plain text but for nicer formatting, you can use Texinfo. In that case, the first line of the help text should be -*- texinfo -*-. There is a page on the Octave wiki with tips on how to write nice help text including a short section on Texinfo syntax (the actual Texinfo manual can be a bit overwhelming).
In addition to the help text, the generate_html package also identifies %!demo blocks and generates a section with the demo code and output it generates, including figures.
The best way to see how help text and demo blocks work in Octave is to check the source (as #Andy pointed out in the comments). For example, see the source for inpolygon (scroll to the bottom to find the %!demo blocks, right before %!test and %!error). The generate_html package generates this page (note the Demonstration blocks).
This is a "multiple questions in one" question, making lots of assumptions in between, so let's address those first:
1. I'll start by the question in the comment, since that's the easiest: Matlab's publisher is not a code documentation tool. It's a "make a quick report that includes both text and code to show at your supervisor meeting or write a quick point in a blog" tool. So the link you point to is simply irrelevant in this case, since that talks about documentation for matlab code.
2. The fact that matlab's publisher also "works for functions", particularly given the first point here, should be considered to be more of a bug than a feature, or at most as a trivial undocumented extension. If you look at the matlab documentation for the publish command, you'll see it expects a filename, not a function with arguments, and the documentation only talks about scripts and makes no mention of 'function' compatibility.
3. Furthermore, even if you did want to use publisher as a "documentation tool", this is counterintuitive for functions in this format, since you need to provide arguments in order for publisher to work (which will not be shown in the actual report), you'll need a modified version that displays intermediate calculations (as opposed to your normal version which presumably does not), and the function just spews an ugly ans= blabla at the end of the report. If your end goal is documentation, it might be best to write a bespoke script for this anyway, showing proper usage and examples, like matlab does in its actual documentation.
Having said all that, yes, there is a 'cheat' you can do to include a function's code in your published report, which is that, in octave (also matlab since R2016b), functions can be defined locally. A .m file that only contains function definitions is interpreted as a function file, but if there are other non-function-declaration instructions preceding the function definitions (other than comments), then it is seen as a script. So if you publish this script, you effectively get a published report with function code in it:
%% Adding function
% This function takes an input and adds 5 to it.
%% Example inputs
In = 10;
%% The function itself
% Marvel at its beauty!
function Out = myfun(In)
%% Here is where the addition takes place.
% It is a beautiful addition
Out = In + 5;
end
%% Example use
Out = myfun(In)
(If you're not happy about having to create a 'wrapper script' manually, you can always create your own wrapper function that does this automatically).
However, both the matlab and octave publishers are limited tools by design. Like I said earlier, it's more of a "quick report to show numbers and plots to your supervisor" tool, rather than a "make nice documentation or professional reports" tool. Instead, I would invest in a nice automated latex workflow, and have a look at code formatting tools for displaying code, and simply wrap that code in a script that produces output to a file that you can then import into latex. It may sound like more work, but it's a lot more flexible and robust in the long term, particularly since the formatting commands can be very quirky as well as limited.
We are trying to implement an automatic markdown generator for an easily maintainable documentation.
When mentioning a variable's type, we would like to prefix it with ? when it is nullable, use backticks around it and add a link to its description. For example: `?[Article](#article)`.
However, the backticks break the link syntax because of the overlap. We use `?`[`Article`](#article) instead to make the link works but it creates a space between ? and Article as follow: ?Article.
Is it possible to make it look like ?Article with a link on Article only?
I just tested this out and discovered that there is no space between ? and Article. What appears to be a space is simply GitHub's styling of two <code> blocks up against each other.
Wrapping the whole thing in backticks won't work because backticks indicate code, and Markdown treats the contents as if they are a code sample where you want to show the source.
The best workaround I can find is to use <code> tags directly:
<code>?[Article](https://stackoverflow.com/)</code>
On both GitHub and Stack Overflow this renders like so:
?Article
(I have used a link to Stack Overflow as the link target here simply so we get a rendered link as an example. I expect that #article will work equally well in your environment.)
In my opinion this is even a reasonable way of doing what you want. Markdown's backticks compile to <code> tags, and inline HTML code is expressly permitted by Markdown:
For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.
It seems that Github does not support the sphinx.ext.doctest syntax in their reStructuredText renderer, which is causing some problems when trying to include a doctest-style code block (.. doctest) in a README.rst which is transcluded into the documentation index (which is rendered by sphinx). If I replace the .. doctest directive with something else, it doesn't render properly as a doctest on Sphinx, but if I don't remove the directive, the code block doesn't render at all (see this gist).
Ideally I'd like to find a solution which just does the right thing in both environments, but failing that, is there a way to fall back to a .. code block or some other supported format (e.g. the rST equivalent of a <NoScript> tag)?