update of packages
This commit is contained in:
345
lisp/ox-tufte/src/README.org
Normal file
345
lisp/ox-tufte/src/README.org
Normal file
@@ -0,0 +1,345 @@
|
||||
#+TITLE: Ox-tufte
|
||||
#+AUTHOR: The Bayesians Inc.
|
||||
|
||||
[[https://melpa.org/#/ox-tufte][file:https://melpa.org/packages/ox-tufte-badge.svg]]
|
||||
[[https://stable.melpa.org/#/ox-tufte][file:https://stable.melpa.org/packages/ox-tufte-badge.svg]]
|
||||
|
||||
* Changes since version 2.x
|
||||
- =ox-tufte-init= is no longer needed in addition to loading the library and has
|
||||
been removed.
|
||||
- inline margin-note syntax changes
|
||||
- inline margin-note-as-macro syntax has been added.
|
||||
- margin-note-as-link syntax has been un-deprecated.
|
||||
- all three inline margin-note syntaxes (=-as-babel-call=, =-as-macro=,
|
||||
=-as-link=) are documented with their respective limitations and quirks.
|
||||
* Introduction
|
||||
[[https://edwardtufte.github.io/tufte-css/][Tufte CSS]] has visually appealing defaults for webpages and supports (among other
|
||||
things) margin and side notes. Unfortunately, /Tufte CSS/ makes a number of
|
||||
demands of the HTML structure. This is a pity, because the HTML generated by
|
||||
=ox-html= breaks some of those assumptions (of =tufte-css=). Using =ox-tufte=
|
||||
you can avail the features of =tufte-css= when exporting an org-mode file to
|
||||
HTML. Since version 2+, the design goal of =ox-tufte= has been to *minimally*
|
||||
change the HTML structure generated by =ox-html= (with additional CSS as needed)
|
||||
to get behaviour that is equivalent to =tufte-css=.
|
||||
|
||||
=ox-tufte= tries very hard to not introduce additional constraints (over and
|
||||
above those imposed by =ox-html= and =tufte-css=) for users. In fact, work on
|
||||
=ox-tufte= [[https://github.com/ox-tufte/ox-tufte/milestone/1][version 2]] began after noticing that:
|
||||
- =ox-tufte= was broken and didn't faithfully reproduce the =tufte-css=
|
||||
experience.
|
||||
- [[https://github.com/Zilong-Li/org-tufte][org-tufte]] made additional assumptions and was too opinionated. E.g.,
|
||||
- deviations from =ox-html=
|
||||
- [[https://github.com/Zilong-Li/org-tufte/blob/404ab1286139ea6cbdc00bb1fb50a0afd9d067de/org-tufte.el#L102][use of katex instead of mathjax]]
|
||||
- [[https://github.com/Zilong-Li/org-tufte/blob/404ab1286139ea6cbdc00bb1fb50a0afd9d067de/org-tufte.el#L87][modified html-template]]
|
||||
- [[https://github.com/Zilong-Li/org-tufte/blob/404ab1286139ea6cbdc00bb1fb50a0afd9d067de/org-tufte.el#L97][automated inclusion of css hosted at third-party location]]
|
||||
|
||||
=ox-tufte= is still a work-in-progress, but it is being used by at least [[https://weary-travelers.gitlab.io/][one
|
||||
blog]] in "production". Please open an issue if you discover any bugs!
|
||||
** Compatibility
|
||||
Ox-tufte is compatible and tested with
|
||||
- =tufte-css= [[https://github.com/edwardtufte/tufte-css/releases/tag/v1.8.0][v1.8.0]]
|
||||
- =org-mode= >= 9.5
|
||||
- =emacs= >= 27.1
|
||||
|
||||
It's worth noting that Emacs 27.1 comes with Org version 9.3 (Org version 9.5
|
||||
comes with Emacs 28.1), however, it can be updated via Emacs's "package menu"
|
||||
(M-x list-packages).
|
||||
|
||||
Please open issues if you discover any incompatibility!
|
||||
* Installation and Usage
|
||||
You can install ox-tufte using [[https://melpa.org][MELPA]]:
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(add-to-list 'package-archives
|
||||
'("melpa" . "http://melpa.org/packages/") t)
|
||||
|
||||
(package-refresh-contents)
|
||||
(package-install 'ox-tufte)
|
||||
#+END_SRC
|
||||
|
||||
And then in your ~init.el~ (or equivalent):
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(require 'ox-tufte)
|
||||
#+END_SRC
|
||||
|
||||
It's important that you download [[https://github.com/edwardtufte/tufte-css][tufte css]] ([[https://github.com/edwardtufte/tufte-css/releases/tag/v1.8.0][v1.8.0]]) and place it on your server
|
||||
(with the fonts).
|
||||
|
||||
** Usage
|
||||
The recommended way to use =ox-tufte= is *with* [[https://orgmode.org/manual/CSS-support.html][the default style provided by
|
||||
ox-html]]. Include =tufte.css= followed by =src/ox-tufte.css= (strictly in that
|
||||
order) in your org-mode document. This can be done by setting [[https://github.com/emacs-straight/org-mode/blob/ca873f7fe47546bca19821f1578a6ab95bf5351c/lisp/ox-html.el#L134][the =:html-head=
|
||||
option for ox-html]]. This can be done in elisp, or done in the specific
|
||||
org-mode document by adding a header such as:
|
||||
#+BEGIN_SRC org
|
||||
,#+HTML_HEAD: <link rel="stylesheet" href="/path/to/tufte.css" type="text/css" />
|
||||
,#+HTML_HEAD: <link rel="stylesheet" href="/path/to/ox-tufte.css" type="text/css" />
|
||||
#+END_SRC
|
||||
|
||||
For usage, when exporting simply select "Tufte HTML" instead of regular HTML
|
||||
export from the export menu (=C-c C-e=).
|
||||
* Features
|
||||
ox-tufte supports *most* of the features from tufte-css, some in different ways
|
||||
than expected, and some extensions.
|
||||
| [[https://edwardtufte.github.io/tufte-css/][Tufte-css concept]] | [[https://orgmode.org/worg/org-syntax.html][Org-mode syntax]] for tufte-css concept | ox-tufte extension |
|
||||
|-----------------------+-------------------------------------------------+---------------------------------------------------|
|
||||
| [[https://edwardtufte.github.io/tufte-css/#fundamentals--sections-and-headers][Sections and Headings]] | Sections and Headings | |
|
||||
| [[https://edwardtufte.github.io/tufte-css/#sidenotes][Sidenotes]] | [[footnotes][Footnotes]] | |
|
||||
| [[https://edwardtufte.github.io/tufte-css/#sidenotes][Margin-notes]] | [[marginnotes-inline][inline babel call]] to [[marginnote]["marginnote" block]] | block margin-notes via "marginnote" special-block |
|
||||
| [[https://edwardtufte.github.io/tufte-css/#epigraphs][Epigraphs]] | [[epigraphs][Quote block]] | |
|
||||
| [[https://edwardtufte.github.io/tufte-css/#figures][iframe wrapper]] | [[figures]["figure"]] org-mode [[https://orgmode.org/org.html#HTML-doctypes][special-block]] | |
|
||||
| [[https://edwardtufte.github.io/tufte-css/#code][Code]] | [[code][Source block]] | |
|
||||
| [[https://edwardtufte.github.io/tufte-css/#imagequilts][ImageQuilts]] | [[quilts][single image or images in"figure" special-block]] | |
|
||||
|
||||
** [[https://edwardtufte.github.io/tufte-css/#sidenotes][Sidenotes and margin-notes]]
|
||||
<<footnotes>>Org-mode footnotes become numbered Sidenotes from the tufte
|
||||
spec. The only limitation (inherited from =tufte-css=) is that a footnote can no
|
||||
longer include another footnote within.
|
||||
*** Inline margin-notes
|
||||
<<marginnotes-inline>>Since, Org-mode doesn't yet support syntax for inline
|
||||
special blocks ([[https://list.orgmode.org/orgmode/87a6b8pbhg.fsf@posteo.net/][though it's being discussed and may be implemented in the near
|
||||
future]]), there are multiple ways to express inline margin-notes (i.e.,
|
||||
margin-notes that can include [[https://html.spec.whatwg.org/#phrasing-content-2][HTML phrasing content]]). Inline margin-notes are
|
||||
implemented in their most feature-full incarnation as an inline babel call,
|
||||
specifically, to [[marginnote][the "marginnote" block defined below]].
|
||||
#+name: marginnote
|
||||
#+header: :var input=""
|
||||
#+begin_src elisp :eval yes :exports results :results html replace value
|
||||
(require 'ox-tufte)
|
||||
(ox-tufte--utils-margin-note input)
|
||||
#+end_src
|
||||
If the only content of an inline margin-note is a link to an image, the
|
||||
generated HTML will be malformed. Use the [[https://orgmode.org/manual/Escape-Character.html][zero width space escape character]] to
|
||||
communicate to the export process that the rendered image is to be contained
|
||||
within a paragraph. If you need to enforce a line break within the margin-note,
|
||||
use =\\= at the end of a line as follows:
|
||||
#+begin_src org
|
||||
This is some regular text call_marginnote("this will be a margin note") and some
|
||||
more text call_marginnote("another margin note.\\
|
||||
new line in second margin note.").
|
||||
#+end_src
|
||||
An alternative syntax of an inline margin-note as a macro is also provided with
|
||||
the following additional (wrt the inline babel call syntax) caveats:
|
||||
- macro invocations are not permitted in this syntax
|
||||
- commas need to be escaped with a backslash (=\=)
|
||||
- line breaks can be enforced by adding an unescaped comma
|
||||
#+begin_src org
|
||||
This is some regular text {{{marginnote(this will be a margin note)}}} and some
|
||||
more text {{{marginnote(another margin note.,new line in second margin
|
||||
note.)}}}.
|
||||
#+end_src
|
||||
If, however, you only need an inline margin-note with some text without
|
||||
requiring specific control over line breaks or insertion of links or images (but
|
||||
still allowing for macro and babel call invocation), the margin-note-as-a-link
|
||||
syntax might be preferable.
|
||||
- The margin note number is optional and either `mn:1` or `mn:` as below would
|
||||
work:
|
||||
#+BEGIN_SRC org
|
||||
This is some regular text [[mn:1][this will be a margin note. while links aren't
|
||||
supported, commas don't need escaping.]] and some more text [[mn:][another margin note]].
|
||||
#+END_SRC
|
||||
The reason for not being able to insert links (or images) using this syntax is
|
||||
an org syntax limitation.
|
||||
*** Block margin-notes
|
||||
There is also support for "block" margin-notes, which are margin-notes that can
|
||||
contain "block" elements ([[https://html.spec.whatwg.org/#flow-content-2][HTML spec flow content]]) such as paragraphs, lists,
|
||||
tables etc. These are defined using an org-mode "marginnote" special-block
|
||||
(i.e., within =#+begin_marginnote= and =#+end_marginnote=, or within
|
||||
=#+BEGIN_marginnote= and =#+END_marginnote=).
|
||||
#+begin_src org
|
||||
,#+begin_marginnote
|
||||
This is a block level margin-note.
|
||||
- item 1
|
||||
- item 2
|
||||
,#+end_marginnote
|
||||
#+end_src
|
||||
The block marginnote is displayed to the right side of the paragraph following
|
||||
it. In case a block margin-note is needed in [[https://orgmode.org/worg/org-syntax.html#Zeroth_section][the zeroth section]] (i.e., before
|
||||
the first heading in an org document), it needs to be wrapped within
|
||||
=#+begin_zeroth-section= and =#+end_zeroth-section= as follows:
|
||||
#+begin_src org
|
||||
,#+begin_zeroth-section
|
||||
,#+begin_marginnote
|
||||
This is a block level margin-note.
|
||||
- item 1
|
||||
- item 2
|
||||
,#+end_marginnote
|
||||
,#+end_zeroth-section
|
||||
#+end_src
|
||||
|
||||
** <<epigraphs>>[[https://edwardtufte.github.io/tufte-css/#epigraphs][Epigraphs]] and [[https://orgmode.org/manual/Paragraphs.html#index-BEGIN_005fVERSE][quotes]]
|
||||
- Anything within =#+begin_epigraph= and =#+end_epigraph= becomes an epigraph
|
||||
(which is a collection of one or more quoted blocks). For example:
|
||||
#+begin_src org
|
||||
,#+begin_epigraph
|
||||
,#+name: quote-1
|
||||
,#+caption: Richard P. Feynman, @@html:<cite>“What Do You Care What Other People Think?”</cite>@@
|
||||
,#+begin_quote
|
||||
For a successful technology, reality must take precedence over public relations,
|
||||
for Nature cannot be fooled.
|
||||
,#+end_quote
|
||||
|
||||
,#+name: quote-2
|
||||
,#+caption: Henri Matisse, @@html:<cite>Henri Matisse Dessins: thèmes et variations</cite>@@ (Paris, 1943), 37
|
||||
,#+begin_quote
|
||||
I do not paint things, I paint only the differences between things.
|
||||
,#+end_quote
|
||||
,#+end_epigraph
|
||||
#+end_src
|
||||
- =ox-tufte= also adds support for =#+CAPTION= on [[https://orgmode.org/manual/Paragraphs.html#index-BEGIN_005fVERSE][org-mode =quote= and =verse= blocks]].
|
||||
** <<code>>[[https://edwardtufte.github.io/tufte-css/#code][Code]]
|
||||
=ox-tufte= uses =ox-html= to export [[https://orgmode.org/manual/Literal-Examples.html][code fragments]] to HTML (without any
|
||||
alteration). =ox-html= and [[https://elpa.nongnu.org/nongnu/htmlize.html][=htmlize=]] allow one to customize the syntax
|
||||
highlighting of the exported code blocks. An Emacs color theme that is visually
|
||||
consistent with =tufte-css= is the [[https://melpa.org/#/plan9-theme][=plan9-theme=]] which can be installed from
|
||||
Melpa via something like:
|
||||
#+begin_src elisp
|
||||
(add-to-list 'package-archives
|
||||
'("melpa" . "http://melpa.org/packages/") t)
|
||||
|
||||
(package-refresh-contents)
|
||||
(package-install 'plan9-theme)
|
||||
#+end_src
|
||||
And then in your =init.el= or equivalent, load it using:
|
||||
src_elisp{(load-theme 'plan9 t)}.
|
||||
** <<figures>>Figures and iframes
|
||||
To use =tufte-css='s =iframe-wrapper= class, one can do something like below:
|
||||
#+begin_src org
|
||||
,#+ATTR_HTML: :class iframe-wrapper
|
||||
,#+begin_figure
|
||||
@@html:<iframe width="853" height="480" src="https://www.youtube.com/embed/YslQ2625TR4" frameborder="0" allowfullscreen></iframe>@@
|
||||
,#+end_figure
|
||||
#+end_src
|
||||
|
||||
To have fullwidth figures:
|
||||
#+begin_src org
|
||||
,#+ATTR_HTML: :class fullwidth
|
||||
,#+begin_figure
|
||||
,#+CAPTION: Edward Tufte’s English translation of the Napoleon’s March data visualization. From Beautiful Evidence, page 122-124.
|
||||
[[https://edwardtufte.github.io/tufte-css/img/napoleons-march.png]]
|
||||
,#+end_figure
|
||||
#+end_src
|
||||
Alternatively, the =fullwidth= class can also be applied to the image
|
||||
directly. However, in this case the resulting image may not truly be
|
||||
"fullwidth".
|
||||
#+begin_src org
|
||||
,#+ATTR_HTML: :class fullwidth
|
||||
,#+CAPTION: Edward Tufte’s English translation of the Napoleon’s March data visualization. From Beautiful Evidence, page 122-124.
|
||||
[[https://edwardtufte.github.io/tufte-css/img/napoleons-march.png]]
|
||||
#+end_src
|
||||
Experiment and choose depending on your application.
|
||||
** <<quilts>>ImageQuilts
|
||||
=tufte-css= has a notion of image quilts. [[https://edwardtufte.github.io/tufte-css/#imagequilts][the examples on tufte-css website]] are
|
||||
single images that were created by combining multiple images. However, that
|
||||
processing was done before linking via html. It's unclear what, if any,
|
||||
conveniences =tufte-css= provides for image quilts (over and above other
|
||||
features, since [[figures][single images can already be included as desired]]).
|
||||
|
||||
However, in =ox-tufte= one can create a figure with multiple images.
|
||||
#+begin_src org
|
||||
,#+HTML_HEAD_EXTRA: <style> .quiltish img { max-height: 200px; min-height: 100px; } </style>
|
||||
,#+attr_html: :class quiltish
|
||||
,#+CAPTION: caption for multiple images
|
||||
,#+begin_figure
|
||||
[[./path/to/img1.png]]
|
||||
[[./path/to/img2.png]]
|
||||
,#+end_figure
|
||||
#+end_src
|
||||
** Deviations and Extensions (from =tufte-css= and =ox-html=)
|
||||
*** Sections and Headings
|
||||
- =h4= heading level is supported in a consistent manner similar to =h3=.
|
||||
*** Epigraphs
|
||||
Epigraphs and quotes by default occupy only the width of the main content. In
|
||||
order to get quoted content that extends for the fullwidth add the =fullwidth=
|
||||
class with an =#+attr_html= annotation.
|
||||
*** Sidenotes and margin-notes
|
||||
- =tufte-css= numbers sidenotes via CSS and as such referring to the same
|
||||
sidenote more than once results in erroneous numbering. =ox-tufte= fixes
|
||||
this.
|
||||
- Block margin-notes are supported via src_org{#+begin_marginnote} and
|
||||
src_org{#+end_marginnote}.
|
||||
*** Figures
|
||||
- Captions on images are placed below the image (as opposed to in the margin
|
||||
area) regardless of whether the image is =fullwidth= or not.
|
||||
*** Code
|
||||
- Since code blocks cannot have footnotes/sidenotes in them, they are treated as
|
||||
if they were using the "fullwidth" class (without having to specify the class
|
||||
via =#+attr_html=).
|
||||
*** ImageQuilts
|
||||
- Unlike =ox-html=, in =ox-tufte= captions on figure special-blocks (the kind
|
||||
used when including multiple images in a block, as in ImageQuilts) are
|
||||
included as figcaptions. *Limitation:* presently the included caption doesn't
|
||||
include automated numbering.
|
||||
** Experimental
|
||||
There may be some experimental extensions in =src/ox-tufte-experimental.css=.
|
||||
If desired, this css file should be included /after/ =src/ox-tufte.css=.
|
||||
* Limitations
|
||||
- The generated HTML is not compatible with [[https://orgmode.org/worg/code/org-info-js/][org-info.js]]. This is because
|
||||
=ox-tufte= customizes the value of =org-html-divs= to align it with what's
|
||||
expected by =tufte-css=.
|
||||
- Code blocks (multiline) currently behave /only/ in a "fullwidth" manner. I.e.,
|
||||
if there is sidenote content from previous paragraph, or a block margin-note
|
||||
it will push the code block down.
|
||||
|
||||
Additionally, =ox-tufte= presently inherits the following limitations from
|
||||
[[https://edwardtufte.github.io/tufte-css/][tufte-css]]:
|
||||
- Footnotes/sidenotes cannot contain nested footnotes/sidenotes.
|
||||
- Sidenotes cannot contain paragraphs, tables etc. (since they are HTML =span=
|
||||
elements).
|
||||
- Captions for =iframe-wrapper= blocks aren't supported.
|
||||
- The generated HTML must (and does) use an =html5= doctype.
|
||||
* Customization
|
||||
** Footnotes section at bottom
|
||||
The behaviour depends on the =:footnotes-section-p= option (which uses the value
|
||||
of ~org-tufte-include-footnotes-at-bottom~ as default).
|
||||
|
||||
Because footnotes are transformed to sidenotes they are currently hidden on very
|
||||
narrow screens (like phones), unless the use manually toggles visibility for
|
||||
each reference. if you want to include footnotes *also* at the bottom of the
|
||||
page, this may be set to =t= using =setq=:
|
||||
#+begin_src elisp
|
||||
(require 'ox-tufte)
|
||||
(setq org-tufte-include-footnotes-at-bottom t)
|
||||
#+end_src
|
||||
Or, if you're using =use-package=:
|
||||
#+begin_src elisp
|
||||
(use-package ox-tufte
|
||||
:config
|
||||
(setq org-tufte-include-footnotes-at-bottom t))
|
||||
#+end_src
|
||||
|
||||
This behaviour can also be configured on a per-file basis using:
|
||||
#+begin_src org
|
||||
,#+OPTIONS: footnotes-section-p:t
|
||||
#+end_src
|
||||
Or, (assuming =org-export-allow-bind-keywords= is =t=) using below:
|
||||
#+begin_src org
|
||||
,#+BIND: org-tufte-include-footnotes-at-bottom t
|
||||
#+end_src
|
||||
** Margin-note symbol and visibility on small screens
|
||||
From [[https://edwardtufte.github.io/tufte-css/][tufte-css]]:
|
||||
#+begin_quote
|
||||
However, on small screens, a margin note is like a sidenote except its
|
||||
viewability-toggle is a symbol rather than a reference number. This document
|
||||
currently uses the symbol ⊕ (⊕), but it’s up to you.
|
||||
#+end_quote
|
||||
This symbol can be tweaked, by modifying the value of
|
||||
=org-tufte-margin-note-symbol=. Specifically, if this value is set to the empty
|
||||
string (=""=), then margin-notes are always hidden on small screens.
|
||||
** Color of margin-note visibility-toggle and footnote-references
|
||||
Margin-note visibility color toggle can be tweaked using something like
|
||||
#+begin_src css
|
||||
label.margin-toggle {
|
||||
color: #a00000;
|
||||
}
|
||||
#+end_src
|
||||
|
||||
For footnote references, something like below would work
|
||||
#+begin_src css
|
||||
label.sidenote-number,
|
||||
.sidenote > sup.numeral {
|
||||
color: #a00000;
|
||||
}
|
||||
#+end_src
|
||||
* References
|
||||
- https://edwardtufte.github.io/tufte-css/
|
||||
- https://gitlab.com/snippets/22309
|
||||
18
lisp/ox-tufte/src/ox-tufte-experimental.css
Normal file
18
lisp/ox-tufte/src/ox-tufte-experimental.css
Normal file
@@ -0,0 +1,18 @@
|
||||
/* NOTE: to be included in page after ox-tufte.css */
|
||||
|
||||
/**********************************************************/
|
||||
/* tufte.css consistent (somewhat opinionated) extensions */
|
||||
/**********************************************************/
|
||||
:root {
|
||||
}
|
||||
|
||||
|
||||
/**********************************************************************************/
|
||||
/* lists in sidenotes - breaks html standard and works only in special situations */
|
||||
/**********************************************************************************/
|
||||
.sidenote dl,
|
||||
.sidenote ol,
|
||||
.sidenote ul {
|
||||
font-size: var(--ox-tufte-note-font-size);
|
||||
line-height: var(--ox-tufte-note-line-height);
|
||||
}
|
||||
467
lisp/ox-tufte/src/ox-tufte.css
Normal file
467
lisp/ox-tufte/src/ox-tufte.css
Normal file
@@ -0,0 +1,467 @@
|
||||
:root {
|
||||
--ox-tufte-content-width: 55%; /* set value consistent with "section > p" */
|
||||
--ox-tufte-fullwidth: 163.636%; /* 90% of body, when ancestor is at 55% */
|
||||
--ox-tufte-src-code-width: 97%;
|
||||
/* 50+5=55% this is what is used by section > {dl, ol, ul} */
|
||||
--ox-tufte-list-width: 50%;
|
||||
--ox-tufte-list-padding-left: 5%;
|
||||
/* font-size and line-height settings from tufte.css */
|
||||
--ox-tufte-content-font-size: 1.4rem;
|
||||
--ox-tufte-content-line-height: 2rem;
|
||||
--ox-tufte-content-epigraph-margin-vertical: calc(5em / 1.4);
|
||||
/* ^ equivalent of 5em when element has 1rem font-size */
|
||||
--ox-tufte-note-line-height: 1.3;
|
||||
--ox-tufte-note-font-size: 1.1rem;
|
||||
--ox-tufte-note-code-font-size: 1rem;
|
||||
--ox-tufte-code-font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
|
||||
--ox-tufte-code-font-size: 1.0rem;
|
||||
--ox-tufte-code-font-size-sans: 1.2rem; /* from ".sans > code" */
|
||||
--ox-tufte-code-line-height: 1.42;
|
||||
/* values tufte.css reuses for h1,h3,h3 */
|
||||
--ox-tufte-heading-font-style: italic;
|
||||
--ox-tufte-heading-font-weight: 400;
|
||||
--ox-tufte-heading-line-height: 1;
|
||||
--ox-tufte-heading-code-font-size: 0.80em;
|
||||
--ox-tufte-heading-min-margin-bottom: 1.4rem; /* h3=1.4rem; p=1.4rem; */
|
||||
--ox-tufte-heading-min-font-size: 1.4rem; /* p=1.4rem; */
|
||||
}
|
||||
|
||||
/* 1. Prevent adjustments of font size after orientation changes in iOS. */
|
||||
/* <https://github.com/necolas/normalize.css/blob/fc091cce1534909334c1911709a39c22d406977b/normalize.css#L13> */
|
||||
html {
|
||||
-webkit-text-size-adjust: 100%; /* 1 */
|
||||
}
|
||||
|
||||
/**************************************************************************/
|
||||
/* re-specify tufte.css values, for compatibility with org-generated html */
|
||||
/**************************************************************************/
|
||||
article { /* add missing default from tufte.css */
|
||||
font-size: var(--ox-tufte-content-font-size);
|
||||
line-height: var(--ox-tufte-content-line-height);
|
||||
}
|
||||
article > p,
|
||||
article > div.epigraph,
|
||||
article > table,
|
||||
article > mjx-container,
|
||||
article > div.zeroth-section,
|
||||
section > div,
|
||||
section > h2 { /* set value consistent with "section > p" */
|
||||
width: var(--ox-tufte-content-width);
|
||||
}
|
||||
article > object {
|
||||
max-width: var(--ox-tufte-content-width);
|
||||
}
|
||||
article figure object {
|
||||
max-width: 100%;
|
||||
}
|
||||
article > p .fullwidth,
|
||||
article > div .fullwidth,
|
||||
section > div .fullwidth {
|
||||
max-width: var(--ox-tufte-fullwidth);
|
||||
width: max-content;
|
||||
}
|
||||
article > blockquote.fullwidth {
|
||||
width: max-content;
|
||||
}
|
||||
@media (max-width: 760px) {
|
||||
div.epigraph > blockquote.fullwidth {
|
||||
width: unset;
|
||||
}
|
||||
}
|
||||
section > dl, section > ol, section > ul,
|
||||
article > dl, article > ol, article > ul {
|
||||
width: var(--ox-tufte-list-width);
|
||||
/* instead of tufte.css's -webkit-padding-start, which doesn't work */
|
||||
padding-inline-start: var(--ox-tufte-list-padding-left);
|
||||
}
|
||||
blockquote .marginnote, blockquote .sidenote {
|
||||
font-style: normal;
|
||||
}
|
||||
/* code blocks. tufte.css also allows for code within headers and
|
||||
* sidenotes/marginnotes. these are currently not supported by us. */
|
||||
.org-src-container {
|
||||
max-width: var(--ox-tufte-fullwidth);
|
||||
width: var(--ox-tufte-fullwidth);
|
||||
clear: both; /* necessary to prevent overlap between long label and sidenote */
|
||||
}
|
||||
body pre { /* monospace content: .src .example */
|
||||
/* FROM: pre.fullwidth > code in tufte.css; but adjusted */
|
||||
width: var(--ox-tufte-src-code-width);
|
||||
clear: both; /* ensure that it doesn't overlap sidenotes */
|
||||
/* unset some unnecessary 'org' defaults, which interfere with tufte */
|
||||
padding-left: 0;
|
||||
padding-right: 0;
|
||||
margin-left: auto;
|
||||
margin-right: 0;
|
||||
}
|
||||
pre, code {
|
||||
/* FROM: "code, pre > code" in tufte.css */
|
||||
font-family: var(--ox-tufte-code-font-family);
|
||||
font-size: var(--ox-tufte-code-font-size);
|
||||
line-height: var(--ox-tufte-code-line-height);
|
||||
}
|
||||
.sans pre, .sans code {
|
||||
font-size: var(--ox-tufte-code-font-size-sans);
|
||||
line-height: var(--ox-tufte-code-line-height);
|
||||
}
|
||||
.sans h1 code, .sans h2 code, .sans h3 code,
|
||||
h1 code, h2 code, h3 code { /* fix for tufte.css */
|
||||
font-size: var(--ox-tufte-heading-code-font-size);
|
||||
}
|
||||
code {
|
||||
vertical-align: middle;
|
||||
}
|
||||
.sidenote code, .marginnote code, /* inline code */
|
||||
.marginnote pre { /* code blocks */
|
||||
font-size: var(--ox-tufte-note-code-font-size);
|
||||
line-height: var(--ox-tufte-note-line-height);
|
||||
}
|
||||
|
||||
article div figure {
|
||||
/* tufte.css doesn't intend figure to be within div, but org generates it as
|
||||
* such. reset width to full width of article as tufte.css intends */
|
||||
max-width: 100%
|
||||
}
|
||||
blockquote p, blockquote footer {
|
||||
width: 100%
|
||||
}
|
||||
|
||||
/**********************************************************/
|
||||
/* tufte.css fixes; should probably be submitted upstream */
|
||||
/**********************************************************/
|
||||
.sans .numeral { /* don't use et-book-roman-old-style when using .sans */
|
||||
font-family: "Gill Sans", "Gill Sans MT", Calibri, sans-serif;
|
||||
}
|
||||
article { /* needed, if sidenotes have large content */
|
||||
/* we don't apply this on "section", because we do want the sections to be
|
||||
* overlappable with the sidenotes of previous section */
|
||||
overflow-y: auto;
|
||||
}
|
||||
|
||||
/****************************/
|
||||
/* unset/alter org defaults */
|
||||
/****************************/
|
||||
#content { /* ID corresponding to main article (excluding pre/postamble) */
|
||||
max-width: 100%;
|
||||
}
|
||||
/* verse */
|
||||
p.verse { /* this verse element will always be within a <blockquote> */
|
||||
/* tufte.css already provides margin-left/right for enclosing blockquote */
|
||||
margin-left: 0;
|
||||
}
|
||||
#footnotes { /* needed, if sidenotes have large content */
|
||||
/* we want to make sure that the footnotes section starts after all the content
|
||||
* for "sections" and "sidenotes" is done */
|
||||
clear: both;
|
||||
width: unset;
|
||||
}
|
||||
|
||||
/***************************/
|
||||
/* undo tufte.css defaults */
|
||||
/***************************/
|
||||
body pre.example { /* in org, this is within blockquote */
|
||||
font-style: normal;
|
||||
}
|
||||
/* verse: undoing "blockquote p, blockquote footer" from tufte.css */
|
||||
div.verse blockquote p, div.verse blockquote footer {
|
||||
width: 100%
|
||||
}
|
||||
|
||||
/********************************************************/
|
||||
/* verse blocks: support and distinguish from epigraphs */
|
||||
/********************************************************/
|
||||
div.verse > blockquote {
|
||||
/* gray bar on the left */
|
||||
border-left: 3px solid #ccc;
|
||||
padding-left: 10px;
|
||||
}
|
||||
|
||||
/***********************************/
|
||||
/* tufte.css consistent extensions */
|
||||
/***********************************/
|
||||
/***************************/
|
||||
/* support for h4 headings */
|
||||
/***************************/
|
||||
h4 > code {
|
||||
font-size: var(--ox-tufte-heading-code-font-size);
|
||||
}
|
||||
h4 {
|
||||
font-style: var(--ox-tufte-heading-font-style);
|
||||
font-weight: var(--ox-tufte-heading-font-weight);
|
||||
margin-bottom: var(--ox-tufte-heading-min-margin-bottom);
|
||||
line-height: var(--ox-tufte-heading-line-height);
|
||||
}
|
||||
h4 {
|
||||
font-size: 1.5rem; /* h3=1.7rem; */
|
||||
margin-top: 1.8rem; /* h3=2rem; */
|
||||
}
|
||||
|
||||
/************************************/
|
||||
/* sidenotes in headings h2, h3, h4 */
|
||||
/************************************/
|
||||
h2 .sidenote, h2 .marginnote,
|
||||
h3 .sidenote, h3 .marginnote,
|
||||
h4 .sidenote, h4 .marginnote {
|
||||
font-style: normal;
|
||||
font-weight: normal;
|
||||
}
|
||||
|
||||
/**********************/
|
||||
/* footnote reference */
|
||||
/**********************/
|
||||
.sidenote-number > sup.numeral, .sidenote > sup.numeral {
|
||||
/* same as ".sidenote-number:after", ".sidenote:before" */
|
||||
font-size: 1rem;
|
||||
line-height: 1rem;
|
||||
}
|
||||
/* we don't rely on CSS numbering */
|
||||
.sidenote-number:after, .sidenote:before {
|
||||
content: none;
|
||||
}
|
||||
|
||||
/****************/
|
||||
/* small screen */
|
||||
/****************/
|
||||
@media (max-width: 760px) {
|
||||
:root {
|
||||
--ox-tufte-content-width: 100%;
|
||||
--ox-tufte-fullwidth: 100%;
|
||||
--ox-tufte-list-width: 90;
|
||||
--ox-tufte-list-padding-left: 10%;
|
||||
}
|
||||
/**********************************************************/
|
||||
/* tufte.css fixes; should probably be submitted upstream */
|
||||
/**********************************************************/
|
||||
.margin-toggle:checked + .sidenote,
|
||||
.margin-toggle:checked + .marginnote {
|
||||
/* what tufte.css does results in minute horizontal scrolling on*/
|
||||
/* sufficiently small screens; below fixes that */
|
||||
margin-left: auto;
|
||||
margin-right: 0;
|
||||
left: 0;
|
||||
float: right;
|
||||
}
|
||||
.marginnote img, .sidenote img {
|
||||
height: auto;
|
||||
width: auto;
|
||||
}
|
||||
}
|
||||
|
||||
/*****************************************************************************/
|
||||
/* assorted bugfixes and additional tweaks */
|
||||
/* NOTE: code below likely needs to be refactored and assimilated into above */
|
||||
/*****************************************************************************/
|
||||
|
||||
|
||||
|
||||
/* BEGIN: width and placement of sidenotes + lists, epigraphs */
|
||||
:root {
|
||||
--ox-tufte-sidenote-width-max: 385px;
|
||||
--ox-tufte-sidenote-width-standard: 50%;
|
||||
--ox-tufte-sidenote-margin-right-min: -462px;
|
||||
--ox-tufte-sidenote-margin-right-standard: -60%;
|
||||
}
|
||||
article > blockquote { /* assuming within an element 55% in width */
|
||||
width: 50%;
|
||||
margin-left: 5%;
|
||||
}
|
||||
blockquote {
|
||||
margin-left: calc(100% / 11);
|
||||
margin-right: 0;
|
||||
}
|
||||
blockquote .sidenote, blockquote .marginnote {
|
||||
min-width: unset;
|
||||
width:calc(var(--ox-tufte-sidenote-width-standard) / (10 / 11));
|
||||
margin-right:calc(var(--ox-tufte-sidenote-margin-right-standard) / (10 / 11));
|
||||
}
|
||||
@media (max-width: 760px) {
|
||||
div.epigraph blockquote p { overflow-y: auto; }
|
||||
}
|
||||
article ul, article ol, article dl {
|
||||
width: var(--ox-tufte-list-width); /* 50% */
|
||||
padding-inline-start: var(--ox-tufte-list-padding-left); /* 5% */
|
||||
}
|
||||
article ul ul, article ol ol, article ul ol, article ol ul {
|
||||
padding-inline-start: calc(100% / 10); /* 5% wrt body, when 100% is 50% */
|
||||
width: calc(100% * 9 / 10); /* 45% wrt body, when 100% is 50% */
|
||||
}
|
||||
article ul ul ul, article ol ol ul, article ul ol ul, article ol ul ul,
|
||||
article ul ul ol, article ol ol ol, article ul ol ol, article ol ul ol {
|
||||
padding-inline-start: calc(100% / 9); /* 5% wrt body, when 100% is 45% */
|
||||
width: calc(100% * 8 / 9); /* 40% wrt body, when 100% is 45% */
|
||||
}
|
||||
section ul, section ol, section dl {
|
||||
padding-inline-start: calc(100% / 11);
|
||||
width: calc(100% * 10 / 11);
|
||||
}
|
||||
article ul .sidenote, article ol .sidenote,
|
||||
article ul .marginnote, article ol .marginnote {
|
||||
width: min(var(--ox-tufte-sidenote-width-max), calc(var(--ox-tufte-sidenote-width-standard) / (10 / 11)));
|
||||
margin-right: max(var(--ox-tufte-sidenote-margin-right-min), calc(var(--ox-tufte-sidenote-margin-right-standard) / (10 / 11)));
|
||||
}
|
||||
article ul ul .sidenote, article ul ul .marginnote,
|
||||
article ul ol .sidenote, article ul ol .marginnote,
|
||||
article ol ol .sidenote, article ol ol .marginnote,
|
||||
article ol ul .sidenote, article ol ul .marginnote { /* 11/9 = 11/10 X(10/9) */
|
||||
width: min(var(--ox-tufte-sidenote-width-max), calc(var(--ox-tufte-sidenote-width-standard) / (9 / 11)));
|
||||
margin-right: max(var(--ox-tufte-sidenote-margin-right-min), calc(var(--ox-tufte-sidenote-margin-right-standard) / (9 / 11)));
|
||||
}
|
||||
article ul ul ul .sidenote, article ul ul ul .marginnote,
|
||||
article ul ul ol .sidenote, article ul ul ol .marginnote,
|
||||
article ul ol ul .sidenote, article ul ol ul .marginnote,
|
||||
article ul ol ol .sidenote, article ul ol ol .marginnote,
|
||||
article ol ol ul .sidenote, article ol ol ul .marginnote,
|
||||
article ol ol ol .sidenote, article ol ol ol .marginnote,
|
||||
article ol ul ul .sidenote, article ol ul ul .marginnote
|
||||
article ol ul ol .sidenote, article ol ul ol .marginnote { /* 11/8 = 11/10 X(10/9) X(9/8) */
|
||||
width: min(var(--ox-tufte-sidenote-width-max), calc(var(--ox-tufte-sidenote-width-standard) / (8 / 11)));
|
||||
margin-right: max(var(--ox-tufte-sidenote-margin-right-min), calc(var(--ox-tufte-sidenote-margin-right-standard) / (8 / 11)));
|
||||
}
|
||||
@media (max-width: 760px) {
|
||||
ul li, ol li {
|
||||
overflow-y: auto;
|
||||
/* however, this causes issues: https://stackoverflow.com/a/40912185 */
|
||||
list-style-position: inside;
|
||||
margin-left: -1em;
|
||||
}
|
||||
}
|
||||
/* fix padding issues first and make them percentages */
|
||||
article dl > dd {
|
||||
margin-left: calc(100% / 10);
|
||||
}
|
||||
/* fix sidenote width and margin-right */
|
||||
article dl dt .sidenote, article dl dt .marginnote {
|
||||
width: min(var(--ox-tufte-sidenote-width-max), calc(var(--ox-tufte-sidenote-width-standard) / (10 / 11)));
|
||||
margin-right: max(var(--ox-tufte-sidenote-margin-right-min), calc(var(--ox-tufte-sidenote-margin-right-standard) / (10 / 11)));
|
||||
font-weight: normal;
|
||||
}
|
||||
article dl dd .sidenote, article dl dd .marginnote { /* 11/9 = 11/10 X(10/9) */
|
||||
width: min(var(--ox-tufte-sidenote-width-max), calc(var(--ox-tufte-sidenote-width-standard) / (9 / 11)));
|
||||
margin-right: max(var(--ox-tufte-sidenote-margin-right-min), calc(var(--ox-tufte-sidenote-margin-right-standard) / (9 / 11)));
|
||||
}
|
||||
/* also check on smaller screens */
|
||||
@media (max-width: 760px) {
|
||||
dl dt, dl dd {
|
||||
overflow-y: auto;
|
||||
}
|
||||
}
|
||||
article dl dl {
|
||||
padding-inline-start: calc(100% / 9); /* 5% wrt body, when 100% is 45% wrt body */
|
||||
width: calc(100% * 8 / 9); /* 40% wrt body */
|
||||
}
|
||||
article dl dl > dd {
|
||||
margin-left: calc(100% / 8) /* 5% wrt body, when 100% is 40% wrt body */
|
||||
}
|
||||
article dl dl dt .sidenote, article dl dl dt .marginnote { /* 11/8 = 11/10 x 10/9 x 9/8 */
|
||||
width: min(var(--ox-tufte-sidenote-width-max), calc(var(--ox-tufte-sidenote-width-standard) / (8 / 11)));
|
||||
margin-right: max(var(--ox-tufte-sidenote-margin-right-min), calc(var(--ox-tufte-sidenote-margin-right-standard) / (8 / 11)));
|
||||
font-weight: normal;
|
||||
}
|
||||
article dl dl dd .sidenote, article dl dl dd .marginnote { /* 11/7 */
|
||||
width: min(var(--ox-tufte-sidenote-width-max), calc(var(--ox-tufte-sidenote-width-standard) / (7 / 11)));
|
||||
margin-right: max(var(--ox-tufte-sidenote-margin-right-min), calc(var(--ox-tufte-sidenote-margin-right-standard) / (7 / 11)));
|
||||
}
|
||||
|
||||
/* BEGIN BONUS: fix top-level code blocks */
|
||||
article>section .org-src-container { /* make .org-src-container in ox-tufte.css more specific */
|
||||
max-width: var(--ox-tufte-fullwidth);
|
||||
width: var(--ox-tufte-fullwidth);
|
||||
}
|
||||
article > div.org-src-container { /* override .org-src-container in ox-tufte.css for toplevel */
|
||||
max-width: 90%;
|
||||
width: 90%;
|
||||
}
|
||||
/* END BONUS: fix top-level code blocks */
|
||||
/* END: width and placement of sidenotes + lists, epigraphs */
|
||||
|
||||
/* BEGIN: width of result blocks */
|
||||
article > pre.example {
|
||||
width: calc(97% * 0.9);
|
||||
margin-right: 10%;
|
||||
}
|
||||
section pre.example {
|
||||
width: calc(var(--ox-tufte-fullwidth) * 0.97);
|
||||
margin-left: calc(var(--ox-tufte-fullwidth) * 0.03);
|
||||
}
|
||||
@media (max-width: 760px) {
|
||||
section pre.example {
|
||||
margin-left: auto;
|
||||
}
|
||||
}
|
||||
/* END: width of result blocks */
|
||||
|
||||
/* BEGIN: fix horizontal scroll on small screens */
|
||||
.org-src-name {
|
||||
display: inline-block;
|
||||
max-width: 100%;
|
||||
overflow-x: auto;
|
||||
}
|
||||
/* END: fix horizontal */
|
||||
|
||||
/* BEGIN: block margin notes */
|
||||
/***************************************************************************/
|
||||
/* block marginnotes - allows us to include lists, paragraphs, tables etc. */
|
||||
/***************************************************************************/
|
||||
article div { /* add missing default from tufte.css */
|
||||
font-size: var(--ox-tufte-content-font-size);
|
||||
line-height: var(--ox-tufte-content-line-height);
|
||||
}
|
||||
div.epigraph {
|
||||
/* NOTE: tufte.css has margins for epigraph in "em" which relies on font-size
|
||||
* for div element not being altered from default; otherwise epigraph margin
|
||||
* will scale with it (<https://zellwk.com/blog/rem-vs-em/>). now epigraphs,
|
||||
* unlike quotes don't have any business in the margin area. but if we did,
|
||||
* it wouldn't make sense to use the same margin absolutely. thus
|
||||
* blockquotes should be in 'em' instead of 'rem'. however, in order to get
|
||||
* same behaviour as tufte either the 'em' value will need to be modified
|
||||
* for epigraph or the font size specified for 'article div' will need to be
|
||||
* modified and will no longer be consistent with 'p'. */
|
||||
margin: var(--ox-tufte-content-epigraph-margin-vertical) 0;
|
||||
}
|
||||
div.marginnote dl,
|
||||
div.marginnote ol,
|
||||
div.marginnote p,
|
||||
div.marginnote ul {
|
||||
font-size: var(--ox-tufte-note-font-size);
|
||||
line-height: var(--ox-tufte-note-line-height);
|
||||
}
|
||||
div.marginnote p {
|
||||
margin-top: var(--ox-tufte-note-font-size);
|
||||
margin-bottom: var(--ox-tufte-note-font-size);
|
||||
}
|
||||
@media (max-width: 760px) {
|
||||
div.marginnote + *, /* needed for block marginnotes */
|
||||
h2, h3, h4, p { /* these are needed for margin/sidenotes in general */
|
||||
clear: both;
|
||||
}
|
||||
}
|
||||
/* END: block margin notes */
|
||||
|
||||
/* BEGIN: captions on figures */
|
||||
figure > figcaption { /* undo tufte-css tweaks, till they're better supported */
|
||||
max-width: unset;
|
||||
float: left;
|
||||
width: 100%;
|
||||
}
|
||||
/* undo tufte-css tweaks, till they're better supported */
|
||||
figure.fullwidth figcaption {
|
||||
margin-right: unset;
|
||||
}
|
||||
img.fullwidth + figcaption {
|
||||
width: var(--ox-tufte-fullwidth);
|
||||
}
|
||||
/* END: captions on figures */
|
||||
|
||||
/* BEGIN: fullwidth images */
|
||||
img.fullwidth {
|
||||
display: block;
|
||||
}
|
||||
/* END: fullwidth images */
|
||||
|
||||
/* BEGIN: prevent side-scroll when result of inline call is long */
|
||||
article code {
|
||||
overflow-x: auto;
|
||||
max-width: 100%;
|
||||
display: inline-block;
|
||||
}
|
||||
/* END: prevent side-scroll when result of inline call is long */
|
||||
Reference in New Issue
Block a user