stevedlawrence commented on code in PR #193: URL: https://github.com/apache/daffodil-site/pull/193#discussion_r2470115814
########## site/_pandoc/README.md: ########## @@ -0,0 +1,223 @@ +--- +layout: page +title: Pandoc + Jekyll Integration +pdf: false +--- +# 🧭 Pandoc + Jekyll Integration + +This directory contains tools for generating **PDF versions** of selected Jekyll pages while keeping the same Markdown files usable by Jekyll for the website. + +The goal is to have **one Markdown source** that: +- renders cleanly in the Jekyll site (for HTML), +- and can also be converted into a polished PDF using **Pandoc + LaTeX**. + +--- + +## 🏗️ Directory Layout + +``` +_pandoc/ +│ +├── README.md ← this file +├── Makefile ← builds all PDFs +├── unwrap-pandoc.awk ← preprocessor that removes comment wrappers +├── template.latex ← (optional) custom LaTeX template +├── header.tex ← (optional) extra LaTeX header content +└── ../pdf/ ← generated PDFs appear here +``` + +At the root of the Jekyll site: + +``` +_config.yml +_posts/ +pages/ +assets/ +_pandoc/ +pdf/ +``` + +--- + +## 🧩 How It Works + +### 1. Mark pages that should have PDFs + +Any Markdown file (in `_posts`, `pages/`, or elsewhere) can be tagged with: + +```yaml +--- +title: Example Page +layout: page +pdf: true +--- +``` + +The Makefile will scan the entire Jekyll project and automatically detect these files. + +--- + +### 2. Use HTML comment wrappers for Pandoc-only content + +Pandoc sometimes needs LaTeX code for things like custom tables, math, or page layout. +We hide that LaTeX from Jekyll using **HTML comments**, which Jekyll ignores but our AWK preprocessor removes before running Pandoc. Review Comment: Yeah, feels like maybe jekyll isn't the best tool for this kind of documentation--it's really just too focused on website generation. Maybe what we need is a tool that is primarily about creating documentation rather than building websites? Something that already supports complex tables, diagrams, etc. and can generate PDFs and/or HTML. Then we can generate the PDF for offline use and HTML for online use. And it's fine if the HTML styling was different from our normal website--we already have Javadocs that use a different style, so it would just be similar to that. And then maybe all of the stuff under the current "Docs" navigation gets migrated to that. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
