Open shamindras opened 2 years ago
Currently Theorem and Proof env are built in bookdown formats only.
There is a way to access some of the feature with other format using what is described in https://bookdown.org/yihui/bookdown/a-single-document.html
output:
bookdown::html_document2:
base_format: distill::distill_article
This should work ok of Theorem I guess
---
title: "Test Title"
description: |
Test description
author: Test author
date: 2021-12-31
output:
bookdown::html_document2:
self_contained: false
base_format: distill::distill_article
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
Trying to ensure that theorem environments are working in distill::distill_article
.
::: {#pythagoras .theorem name="Pythagorean theorem"} For a right triangle, if $c$ denotes the length of the hypotenuse and $a$ and $b$ denote the lengths of the other two sides, we have
$$a^2 + b^2 = c^2$$ :::
We have a labeled and named theorem below, and \@ref(thm:pythagoras).
![image](https://user-images.githubusercontent.com/6791940/148065835-43aaca17-cf31-4648-9927-be4b5ccfa1bf.png)
You would get the same HTML rendering as in **bookdown**.
Unfortunately, this is not 100% accurate as all of the **bookdown** features won't work within a **distill** document. Related issue #287 which is linked to https://github.com/rstudio/bookdown/issues/1077
This is definitely something to improve and maybe built in within **distill**. Thanks for the report!
We are also working on new stuff regarding scientific publishing and those type of consideration (theorem and other env from LaTeX to be available to HTML) is in our concerns.
@cderv - this is a very cool solution, and more in line with what I was expecting to change (i.e., yaml
). I just tested and the main bookdown environments seem to work in the distill blog article I'm writing. I'll post back if there are any issues as I play with this more.
Could you please post your solution to my stackoverflow post? I can accept it as the official solution. Posting there in your capacity will help other users. Otherwise, I'll add it myself and make sure to credit and link to your approach later today.
One question, I understand that rendering these environments in distill::distill_article
is mainly an issue with mathjax
. I dug into the bookdown
implementation of these environments. I found it is done here (there may be other files as well). Is it possible to load this lua
file into the distill
mathjax
environment to make this easier to customize for distill
purposes? Just a thought.
Could you please post your solution to my stackoverflow post?
Will do.
One question, I understand that rendering these environments in distill::distill_article is mainly an issue with mathjax. I dug into the bookdown implementation of these environments. I found it is done here (there may be other files as well). Is it possible to load this lua file into the distill mathjax environment to make this easier to customize for distill purposes? Just a thought.
Rendering LaTeX Math in HTML document is a matter of Mathjax. (i.e \begin{equation}
). This is different and this is a JS library.
For theorems and proofs environments, they are only available in LaTeX originally. However, in bookdown there is a special process to handle those environments to mimic them in a HTML output. But as you see, you don't write LaTeX, you write a special markdown syntax (using fenced div with class) that allow us to handle multi format by writing the expected output (either LaTeX or HTML). Recently, we've put the logic into the lua filter so technically you could indeed use only this but it was not designed as portable so I am not sure everything is working 100% (the referencing is not done in Lua for example I believe). This would be done like this
output:
distill::distill_article:
self_contained: false
pandoc_args: !expr rmarkdown::pandoc_lua_filter_args(rmarkdown::pkg_file_lua("custom-environment.lua", "bookdown"))
It seems it works but I am unsure why. However, you're right that this would be the way to go when we tackle the idea of making this a more generic feature: use a lua filter that we can use for different formats.
You could be interested in a new project currently in development that aim to take the experience of R Markdown and other publishing tool to create an improved version, still based on Pandoc, for scientific publishing and content creation which is language agnostic: https://quarto.org. It already have feature like Theorems (here) and other feature found in distill (like layout) but it does not have a distill format per-se. Anyway, you may be interested to follow the work there too.
Could you please post your solution to my stackoverflow post?
Will do.
Thanks! I just accepted this answer 👍🏾 .
One question, I understand that rendering these environments in distill::distill_article is mainly an issue with mathjax. I dug into the bookdown implementation of these environments. I found it is done here (there may be other files as well). Is it possible to load this lua file into the distill mathjax environment to make this easier to customize for distill purposes? Just a thought.
Rendering LaTeX Math in HTML document is a matter of Mathjax. (i.e
\begin{equation}
). This is different and this is a JS library.For theorems and proofs environments, they are only available in LaTeX originally. However, in bookdown there is a special process to handle those environments to mimic them in a HTML output. But as you see, you don't write LaTeX, you write a special markdown syntax (using fenced div with class) that allow us to handle multi format by writing the expected output (either LaTeX or HTML). Recently, we've put the logic into the lua filter so technically you could indeed use only this but it was not designed as portable so I am not sure everything is working 100% (the referencing is not done in Lua for example I believe). This would be done like this
output: distill::distill_article: self_contained: false pandoc_args: !expr rmarkdown::pandoc_lua_filter_args(rmarkdown::pkg_file_lua("custom-environment.lua", "bookdown"))
It seems it works but I am unsure why. However, you're right that this would be the way to go when we tackle the idea of making this a more generic feature: use a lua filter that we can use for different formats.
This seems quite interesting and promising. The lua-filter
does seem like a more flexible way to customize LaTeX
for such rmarkdown related purposes. Could be cool to see more of the bookdown features implemented in distill
.
You could be interested in a new project currently in development that aim to take the experience of R Markdown and other publishing tool to create an improved version, still based on Pandoc, for scientific publishing and content creation which is language agnostic: quarto.org. It already have feature like Theorems (here) and other feature found in distill (like layout) but it does not have a distill format per-se. Anyway, you may be interested to follow the work there too.
This looks very cool indeed! Thanks for flagging it. I'm currently tied to distill
and seeing how it works for my site and blogging, but this looks like a really promising toolkit to consider if I move to a more language agnostic blog and website. Appreciate you flagging it.
Could be cool to see more of the bookdown features implemented in distill.
Do not hesitate to open more feature request for what you found missing, or add a 👍 if there is already one open !
Hi. If we are using a language other than English, for example, we may want to write "Teorem" instead of "Theorem". We can do this with language in the _bookdown.yml
file in bookdown. Is there a way in Distill? I tried the _site.yml
file and it didn't work.
@acarzfr There is currently no localization / internationalization feature in distill. See old https://github.com/rstudio/distill/issues/50 about this.
Regarding bookdown feature, the internationalization as described in the doc for bookdown works but distill and bookdown does not play well together (HTML5 vs HTML4). So not 100% sure it works. From bookdown documentation, the file that the bookdown feature will use is _bookdown.yml
.
@cderv Thanks for the answer.
I'm an active
distill
user and am grateful for this nice blogging package.I plan to write more technical math related posts and wanted to use
LaTeX
environments, e.g.,theorem
,lemma
,corollary
etc. I've previously asked about #101.I recently revived this discussion on stackoverflow. I received a thoughtful solution where a user made many detailed modifications to the CSS to get it working. As a result I'm intentionally cross-posting and raising this an issue here.
Basically, I was a little surprised that
distill
users would need to go to such lengths to makeLaTeX
environments work, given that bookdown has implementedrmarkdown
versions here and here. I wanted to flag it with thedistill
team to get the official approach to this.Here is the minimal reprex to help understand the issue (from the stackoverflow post above).
TL;DR;
Trying to ensure that theorem environments are working in
distill::distill_article
.Main theorems
With the definitional background established, let's move onto the main theorem of this article.
\begin{align} g(X{n}) &= g(\theta)+g'({\tilde{\theta}})(X{n}-\theta) \notag \ \sqrt{n}[g(X{n})-g(\theta)] &= g'\left({\tilde{\theta}}\right) \sqrt{n}[X{n}-\theta ] (#eq:align) \end{align}
\begin{theorem}[Delta Method]\label{nthm:deltamethod} g(X{n}) &= g(\theta)+g'({\tilde{\theta}})(X{n}-\theta) \notag \ \sqrt{n}[g(X{n})-g(\theta)] &= g'\left({\tilde{\theta}}\right) \sqrt{n}[X{n}-\theta ] (#eq:align) \end{theorem}
We have a labeled and named theorem below, and \@ref(nthm:deltamethod).
::: {.theorem #pythagoras name="Pythagorean theorem"} For a right triangle, if $c$ denotes the length of the hypotenuse and $a$ and $b$ denote the lengths of the other two sides, we have
$$a^2 + b^2 = c^2$$ :::
We have a labeled and named theorem below, and \@ref(thm:pythagoras).