Skip to content

Commit 2e677ea

Browse files
jeremymanningjeremymanning
authored
Merge pull request #178 from ContextLab/feature/html-version
Add HTML version of lab manual with GitHub Pages deployment
2 parents 6373ac6 + 1f61f92 commit 2e677ea

File tree

6 files changed

+314
-0
lines changed

6 files changed

+314
-0
lines changed

‎.github/workflows/build-html.yml‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
name: Build HTML Lab Manual
2+
3+
on:
4+
push:
5+
branches: [master]
6+
paths:
7+
- 'lab_manual.tex'
8+
- 'tufte.cfg'
9+
- 'toc.js'
10+
- 'lab-manual.css'
11+
- '.github/workflows/build-html.yml'
12+
pull_request:
13+
branches: [master]
14+
paths:
15+
- 'lab_manual.tex'
16+
- 'tufte.cfg'
17+
- 'toc.js'
18+
- 'lab-manual.css'
19+
workflow_dispatch: # Allow manual triggering
20+
21+
permissions:
22+
contents: read
23+
pages: write
24+
id-token: write
25+
26+
# Only allow one deployment at a time
27+
concurrency:
28+
group: "pages"
29+
cancel-in-progress: false
30+
31+
jobs:
32+
build-html:
33+
runs-on: ubuntu-latest
34+
35+
steps:
36+
- name: Checkout repository
37+
uses: actions/checkout@v4
38+
39+
- name: Install TeX Live
40+
run: |
41+
sudo apt-get update
42+
sudo apt-get install -y texlive-latex-extra texlive-fonts-extra texlive-plain-generic tex4ht
43+
44+
- name: Run make4ht conversion
45+
run: |
46+
mkdir -p html_output
47+
make4ht -u -c tufte.cfg -d html_output lab_manual.tex "mathml,mathjax" || true
48+
# List what was generated
49+
ls -la html_output/ || echo "html_output directory contents check"
50+
51+
- name: Download Tufte CSS assets
52+
run: |
53+
# Download tufte.css
54+
curl -sL -o html_output/tufte.css https://raw.githubusercontent.com/edwardtufte/tufte-css/gh-pages/tufte.css
55+
56+
# Download ET Book fonts
57+
mkdir -p html_output/et-book
58+
for font in et-book-roman-line-figures et-book-roman-old-style-figures et-book-semi-bold-old-style-figures et-book-bold-line-figures; do
59+
curl -sL -o "html_output/et-book/${font}.ttf" "https://github.com/edwardtufte/tufte-css/raw/gh-pages/et-book/${font}.ttf" 2>/dev/null || true
60+
curl -sL -o "html_output/et-book/${font}.woff" "https://github.com/edwardtufte/tufte-css/raw/gh-pages/et-book/${font}.woff" 2>/dev/null || true
61+
done
62+
63+
# Copy lab logo
64+
cp -r lab_logo html_output/
65+
66+
# Copy custom files (toc.js for table of contents)
67+
cp toc.js html_output/
68+
69+
# Rename main HTML file to index.html if needed
70+
if [ -f html_output/lab_manual.html ] && [ ! -f html_output/index.html ]; then
71+
cp html_output/lab_manual.html html_output/index.html
72+
fi
73+
74+
- name: List output files
75+
run: ls -la html_output/
76+
77+
- name: Upload HTML artifact
78+
uses: actions/upload-artifact@v4
79+
with:
80+
name: html-lab-manual
81+
path: html_output/
82+
retention-days: 30
83+
84+
# Deploy to GitHub Pages only on push to master
85+
deploy:
86+
if: github.ref == 'refs/heads/master' && github.event_name == 'push'
87+
needs: build-html
88+
runs-on: ubuntu-latest
89+
90+
environment:
91+
name: github-pages
92+
url: ${{ steps.deployment.outputs.page_url }}
93+
94+
steps:
95+
- name: Download artifact
96+
uses: actions/download-artifact@v4
97+
with:
98+
name: html-lab-manual
99+
path: html_output
100+
101+
- name: Setup Pages
102+
uses: actions/configure-pages@v4
103+
104+
- name: Upload to GitHub Pages
105+
uses: actions/upload-pages-artifact@v3
106+
with:
107+
path: html_output
108+
109+
- name: Deploy to GitHub Pages
110+
id: deployment
111+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,16 @@ lab_manual.ilg
1111
lab_manual.fdb_latexmk
1212
lab_manual.ind
1313
lab_manual.blg
14+
15+
# TeX4ht build artifacts
16+
*.4ct
17+
*.4tc
18+
*.css
19+
*.dvi
20+
*.idv
21+
*.lg
22+
*.tmp
23+
*.xref
24+
lab_manual.html
25+
html_output/
26+
html_test/

‎CLAUDE.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Repository Overview
6+
7+
This is the lab manual for the Contextual Dynamics Laboratory (CDL) at Dartmouth College. It's a LaTeX document using the Tufte-book class that describes lab policies, member responsibilities, and research approach.
8+
9+
## Build Commands
10+
11+
**Compile the PDF:**
12+
```bash
13+
./compile.sh
14+
```
15+
16+
This runs `latex` multiple times (for cross-references and index), then `pdflatex`, and cleans up intermediate files. Requires a LaTeX distribution (e.g., `brew install --cask mactex` on macOS).
17+
18+
**HTML version:** The HTML version is automatically generated via GitHub Actions when changes are pushed to master. No manual build is needed. The workflow uses make4ht (TeX4ht) with `tufte.cfg` configuration to convert to tufte-css styled HTML.
19+
20+
## Project Structure
21+
22+
- `lab_manual.tex` - Main document source (single file containing all content)
23+
- `lab_manual.pdf` - Compiled output (committed to repo)
24+
- `tufte.cfg` - TeX4ht configuration for HTML generation
25+
- `tufte-book.cls`, `tufte-common.def`, `tufte-handout.cls` - Custom Tufte template files
26+
- `lab_logo/` - Lab logo images (PNG, PDF)
27+
- `resources/` - Additional resources (cheatsheets, cluster tutorials)
28+
- `.github/workflows/` - CI/CD workflows (LaTeX validation, HTML generation)
29+
30+
## LaTeX Conventions
31+
32+
The document uses several custom commands defined in `lab_manual.tex`:
33+
- `\marginnote{}` - For margin notes (TASK items and NOTEs)
34+
- `\newthought{}` - For section introductions
35+
- `\ourschool` - Expands to "Dartmouth College"
36+
- `\director`, `\coordinator` - Lab director references
37+
- Links use `dartmouthgreen` color (RGB: 0, 105, 62)
38+
39+
## Workflow Notes
40+
41+
After editing `lab_manual.tex`:
42+
1. Run `./compile.sh` to regenerate the PDF
43+
2. Verify the PDF looks correct (check TOC links, margin notes positioning)
44+
3. Commit both the `.tex` source and updated `.pdf`

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ All new lab members are required to read (and modify!) this repository *prior* t
66

77
A PDF of the latest version of the lab manual may always be found [here](https://github.com/ContextLab/lab-manual/blob/master/lab_manual.pdf).
88

9+
An HTML version is also available at [contextlab.github.io/lab-manual](https://contextlab.github.io/lab-manual/). The HTML version is automatically generated from the LaTeX source whenever changes are pushed to the master branch.
10+
911
## Building the PDF
1012
To compile a PDF of the lab manual, you need to first install a working distribution of [LaTeX](https://www.latex-project.org/get/). If you're on a mac with [homebrew](https://brew.sh/), you can run `brew install --cask mactex`.
1113

‎toc.js‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// Generate table of contents from h2.chapterHead elements
2+
document.addEventListener('DOMContentLoaded', function() {
3+
var toc = document.getElementById('toc-list');
4+
if (!toc) return;
5+
6+
var headings = document.querySelectorAll('h2.chapterHead');
7+
headings.forEach(function(h) {
8+
var li = document.createElement('li');
9+
var a = document.createElement('a');
10+
a.href = '#' + h.id;
11+
a.textContent = h.textContent;
12+
li.appendChild(a);
13+
toc.appendChild(li);
14+
});
15+
});

‎tufte.cfg‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
% tufte.cfg - TeX4ht configuration for Tufte-LaTeX to Tufte-CSS HTML conversion
2+
% Based on: https://tex.stackexchange.com/questions/570630/can-a-tufte-latex-file-output-tufte-css-html
3+
% Reference: https://edwardtufte.github.io/tufte-css/
4+
5+
\Preamble{xhtml}
6+
\Configure{AddCss}{tufte.css}
7+
8+
% Helper macro to close current paragraph
9+
\def\endparagraph{\ifvmode\IgnorePar\fi\EndP}
10+
11+
% Configure body to use article wrapper (tufte-css convention)
12+
\Configure{@BODY}{\endparagraph\HCode{<article>}}
13+
\Configure{@/BODY}{\endparagraph\HCode{</article>}}
14+
15+
% Configure sections (Tufte LaTeX makes \section and \subsection behave like starred versions)
16+
\Configure{likesection}
17+
{\endparagraph\HCode{<section>}}{\endparagraph\HCode{</section>}}
18+
{\HCode{<h2 class="chapterHead">}}{\HCode{</h2>}\par\ShowPar}
19+
20+
\Configure{likesubsection}
21+
{\endparagraph\HCode{<section>}}{\endparagraph\HCode{</section>}}
22+
{\HCode{<h3 class="subsectionHead">}}{\HCode{</h3>}\par\ShowPar}
23+
24+
% Simple table of contents - will be populated by JavaScript
25+
\renewcommand\tableofcontents{%
26+
\endparagraph%
27+
\HCode{<nav id="toc" class="toc"><h2>Contents</h2><ul id="toc-list"></ul></nav>}%
28+
\HCode{<script src="toc.js"></script>}%
29+
}
30+
31+
\makeatletter
32+
33+
% Configure title page
34+
\renewcommand{\maketitle}{%
35+
\begingroup%
36+
\endparagraph\HCode{<h1>}\@title\HCode{</h1>}%
37+
\HCode{<p class="subtitle">}\@author\HCode{</p>}%
38+
\HCode{<p class="subtitle">}\@date\HCode{</p>}%
39+
\endgroup
40+
}
41+
42+
% Configure image dimensions
43+
\Configure{Gin-dim}{}
44+
\Css{img {
45+
max-width: 100\%;
46+
height: auto;
47+
}}
48+
49+
% Fix soul package compatibility (for \allcaps, \smallcaps)
50+
\@ifpackageloaded{soul}{%
51+
\renewcommand{\allcaps}[1]{\MakeTextUppercase{#1}}%
52+
\renewcommand{\smallcaps}[1]{{\scshape\MakeTextLowercase{#1}}}%
53+
\renewcommand{\textsc}[1]{\textcaps{#1}}%
54+
}{}
55+
56+
% Configure sidenotes with tufte-css checkbox toggle pattern
57+
\long\def\@tufte@sidenote[#1][#2]#3{%
58+
\stepcounter\@mpfn%
59+
\bgroup%
60+
\HCode{<label for="sidenote-\thempfn" class="margin-toggle sidenote-number"></label><input type="checkbox" id="sidenote-\thempfn" class="margin-toggle" />}%
61+
\HCode{<span class="sidenote">}#3\HCode{</span>}%
62+
\egroup%
63+
}
64+
65+
% Configure margin notes (unnumbered)
66+
% Use Unicode character directly for the circle-plus symbol
67+
\renewcommand\marginnote[2][0pt]{%
68+
\stepcounter\@mpfn%
69+
\bgroup%
70+
\HCode{<label for="marginnote-\thempfn" class="margin-toggle">⊕</label><input type="checkbox" id="marginnote-\thempfn" class="margin-toggle" />}%
71+
\HCode{<span class="marginnote">}#2\HCode{</span>}%
72+
\egroup%
73+
}
74+
75+
% Configure verbatim environments
76+
\ConfigureEnv{verbatim}{\endparagraph\HCode{<pre><code>}\NoFonts}{\EndNoFonts\endparagraph\HCode{</code></pre>}}{}{}
77+
78+
% Configure fullwidth environment
79+
\ConfigureEnv{fullwidth}{\endparagraph\HCode{<div class="fullwidth">}%
80+
\ConfigureList{list}{}{}{}{}%
81+
\par\ShowPar\indent%
82+
}
83+
{\endparagraph\HCode{</div>}}{}{}
84+
85+
% Configure margin floats (marginfigure)
86+
\NewConfigure{marginfloat}{2}
87+
88+
\renewenvironment{@tufte@margin@float}[2][-1.2ex]%
89+
{\FloatBarrier%
90+
\begingroup%
91+
\let\textwidth\marginparwidth%
92+
\def\@captype{#2}%
93+
\par%
94+
\Configure{HtmlPar}{\EndP\csname a:marginfloat\endcsname}{\EndP\csname a:marginfloat\endcsname}{\csname b:marginfloat\endcsname}{\csname b:marginfloat\endcsname}%
95+
}
96+
{\endgroup}
97+
98+
\Configure{marginfloat}{\HCode{<p><span class="marginnote">}%
99+
\Configure{caption}{\HCode{<span class="figure">}}{:\space}{}{\HCode{</span>}}%
100+
}{\HCode{</span></p>}}{}{}
101+
102+
\Css{.marginnote .figure{display:block;}}
103+
104+
% Configure regular floats
105+
\renewenvironment{@tufte@float}[3][htbp]%
106+
{\@float{#2}[#1]}{\end@float}
107+
108+
% Configure captions
109+
\Configure{caption}{\HCode{<span class="marginnote">}}{:\space}{}{\HCode{</span>}}
110+
111+
% Configure fullwidth figures (figure*)
112+
\ConfigureEnv{figure*}{
113+
\Configure{float}{}{\endparagraph\HCode{<figure class="fullwidth">}}{\endparagraph\HCode{</figure>}\csname par\endcsname\ShowPar}
114+
\Configure{caption}{\endparagraph\HCode{<span class="figure">}}{:\space}{}{\HCode{</span>}}
115+
}{}{}{}
116+
117+
% Configure margin tables
118+
\ConfigureEnv{margintable}{\endparagraph\HCode{<div class="margintable">}\Configure{caption}{}{:\space}{}{}}{\endparagraph\HCode{</div>}}{}{}
119+
120+
% Configure math display width to match tufte-css article width
121+
\Css{div.math-display, div.par-math-display {width: 55\%}}
122+
123+
% Add custom stylesheet (loaded after tufte.css)
124+
\Configure{AddCss}{lab-manual.css}
125+
126+
\makeatother
127+
128+
\begin{document}
129+
\EndPreamble

0 commit comments

Comments
 (0)