From efe296dcf549e33b82d700d12e2927610a45c6c2 Mon Sep 17 00:00:00 2001 From: Dakshata Mishra Date: Sun, 22 Feb 2026 17:18:35 +0000 Subject: [PATCH 1/2] feat: include tutorials in PDF and optimize file size - Updated prince-list.txt and tocpage.html to include tutorials - Integrated --raster-images-res 150 flag in pdf-docs.sh to reduce size - Documented optimizations in docs-meta-publish-to-pdf.md --- .../docs-meta/docs-meta-publish-to-pdf.md | 12 ++- pdf-docs.sh | 3 +- pdfconfigs/config_docs_pdf.yml | 3 + pdfconfigs/prince-list.txt | 59 ++++++++---- pdfconfigs/tocpage.html | 95 ++++++++++++------- 5 files changed, 117 insertions(+), 55 deletions(-) diff --git a/content/docs/docs-meta/docs-meta-publish-to-pdf.md b/content/docs/docs-meta/docs-meta-publish-to-pdf.md index 037636c88fe..7fedc969277 100644 --- a/content/docs/docs-meta/docs-meta-publish-to-pdf.md +++ b/content/docs/docs-meta/docs-meta-publish-to-pdf.md @@ -73,7 +73,7 @@ http://localhost:4000/docs.html This list is consumed by Prince and converted into PDF: ```bash -prince --javascript --input-list=_site/pdfconfigs/prince-list.txt -o pdf/docs.pdf +prince --javascript --raster-images-res 150 --input-list=_site/pdfconfigs/prince-list.txt -o pdf/docs.pdf ``` The final PDF can be found in `pdf/docs.pdf` as specified. The `--javascript` option enables JavaScript support. @@ -106,10 +106,16 @@ For further reference consult the [documentation of documentation-theme-jekyll]( ## Contents, title page and table of contents -The PDF will contain every page of type `pdf` that is referenced in the sidebar `pdf_sidebar` in `pdfconfigs/config_docs_pdf.yml`. E.g. if +The PDF will contain every page of type `pdf` that is referenced in the sidebars configured in `pdfconfigs/config_docs_pdf.yml`. +You can configure a single sidebar via `pdf_sidebar` or multiple sidebars via `pdf_sidebars`. E.g. if ```yml pdf_sidebar: docs_sidebar + + +pdf_sidebars: + - docs_sidebar + - tutorial_sidebar ``` and `docs_sidebar.yml` is @@ -130,6 +136,8 @@ and `docs_sidebar.yml` is the PDF will contain `apples.html` but not `oranges.html`. +For `tutorial_sidebar`, all entries with output `web` are also included in the PDF build. + Furthermore two more pages have to be included in `docs_sidebar.yml`: ```yml diff --git a/pdf-docs.sh b/pdf-docs.sh index b534b5ec43b..a17c8bb5ae5 100644 --- a/pdf-docs.sh +++ b/pdf-docs.sh @@ -10,8 +10,7 @@ bundle exec jekyll serve --detach --config _config.yml,pdfconfigs/config_docs_pd echo "done"; echo "Building the PDF ..."; -prince --javascript --input-list=_site/pdfconfigs/prince-list.txt -o pdf/docs.pdf; - +prince --javascript --raster-images-res 150 --input-list=_site/pdfconfigs/prince-list.txt -o pdf/docs.pdf; echo "Done. Look in the pdf directory to see if it printed successfully." # bundle exec jekyll serve --config "_config.yml,pdfconfigs/config_docs_pdf.yml" diff --git a/pdfconfigs/config_docs_pdf.yml b/pdfconfigs/config_docs_pdf.yml index 333a229d08d..7488961b59e 100644 --- a/pdfconfigs/config_docs_pdf.yml +++ b/pdfconfigs/config_docs_pdf.yml @@ -17,3 +17,6 @@ defaults: search: true pdf_sidebar: docs_sidebar +pdf_sidebars: + - docs_sidebar + - tutorial_sidebar diff --git a/pdfconfigs/prince-list.txt b/pdfconfigs/prince-list.txt index d8f3fd13608..93ba686938d 100644 --- a/pdfconfigs/prince-list.txt +++ b/pdfconfigs/prince-list.txt @@ -3,28 +3,49 @@ layout: none search: exclude --- - {% assign sidebar = site.data.sidebars[site.pdf_sidebar].entries %} + {% assign docs_sidebar = site.data.sidebars.docs_sidebar.entries %} + {% assign tutorial_sidebar = site.data.sidebars.tutorial_sidebar.entries %} - {% for entry in sidebar %} + {% for entry in docs_sidebar %} + {% for folder in entry.folders %} + {% if folder.output contains "pdf" %} + {% for folderitem in folder.folderitems %} + {% if folderitem.output contains "pdf" %} + {{site.url}}{{site.baseurl}}{{folderitem.url}} + {% for subfolders in folderitem.subfolders %} + {% if subfolders.output contains "pdf" %} + {% for subfolderitem in subfolders.subfolderitems %} + {% if subfolderitem.output contains "pdf" %} + {{site.url}}{{site.baseurl}}{{subfolderitem.url}} + {% endif %} + {% endfor %} + {% endif %} + {% endfor %} + {% endif %} + {% endfor %} + {% endif %} + {% endfor %} + {% endfor %} - {% for folder in entry.folders %} - {% if folder.output contains "pdf" %} - {% for folderitem in folder.folderitems %} - {% if folderitem.output contains "pdf" %} - {{site.url}}{{site.baseurl}}{{folderitem.url}} - {% for subfolders in folderitem.subfolders %} - {% if subfolders.output contains "pdf" %} - {% for subfolderitem in subfolders.subfolderitems %} - {% if subfolderitem.output contains "pdf" %} - {{site.url}}{{site.baseurl}}{{subfolderitem.url}} + {% for entry in tutorial_sidebar %} + {% for folder in entry.folders %} + {% if folder.output contains "web" %} + {% for folderitem in folder.folderitems %} + {% if folderitem.output contains "web" %} + {{site.url}}{{site.baseurl}}{{folderitem.url}} + {% for subfolders in folderitem.subfolders %} + {% if subfolders.output contains "web" %} + {% for subfolderitem in subfolders.subfolderitems %} + {% if subfolderitem.output contains "web" %} + {{site.url}}{{site.baseurl}}{{subfolderitem.url}} + {% endif %} + {% endfor %} {% endif %} - {% endfor %} - {% endif %} - {% endfor %} - {% endif %} - {% endfor %} - {% endif %} - {% endfor %} + {% endfor %} + {% endif %} + {% endfor %} + {% endif %} + {% endfor %} {% endfor %} diff --git a/pdfconfigs/tocpage.html b/pdfconfigs/tocpage.html index 61181965026..45bfc7e7e82 100644 --- a/pdfconfigs/tocpage.html +++ b/pdfconfigs/tocpage.html @@ -8,37 +8,68 @@ From 5d60aec5fce5d83d9ce1bd39f8317ee3edc63137 Mon Sep 17 00:00:00 2001 From: Dakshata Mishra Date: Sun, 1 Mar 2026 13:27:58 +0000 Subject: [PATCH 2/2] Fix PDF sidebar config and add separators --- .../docs-meta/docs-meta-publish-to-pdf.md | 6 ++--- pdfconfigs/config_docs_pdf.yml | 2 +- pdfconfigs/docs_part_title.html | 8 ++++++ pdfconfigs/prince-list.txt | 26 +++++++++++-------- pdfconfigs/tocpage.html | 10 ++++--- pdfconfigs/tutorials_part_title.html | 8 ++++++ 6 files changed, 41 insertions(+), 19 deletions(-) create mode 100644 pdfconfigs/docs_part_title.html create mode 100644 pdfconfigs/tutorials_part_title.html diff --git a/content/docs/docs-meta/docs-meta-publish-to-pdf.md b/content/docs/docs-meta/docs-meta-publish-to-pdf.md index 7fedc969277..7d4334439f8 100644 --- a/content/docs/docs-meta/docs-meta-publish-to-pdf.md +++ b/content/docs/docs-meta/docs-meta-publish-to-pdf.md @@ -17,7 +17,7 @@ On a Windows environment it makes sense to add the location of the Prince execut The bash script 'pdf-docs.sh' in root can be used to build the PDF. It goes through the following steps -### Build a web target with jekll +### Build a web target with jekyll First, let's kill all running instances of jekyll: @@ -73,7 +73,7 @@ http://localhost:4000/docs.html This list is consumed by Prince and converted into PDF: ```bash -prince --javascript --raster-images-res 150 --input-list=_site/pdfconfigs/prince-list.txt -o pdf/docs.pdf +prince --javascript --raster-dpi=150 --input-list=_site/pdfconfigs/prince-list.txt -o pdf/docs.pdf ``` The final PDF can be found in `pdf/docs.pdf` as specified. The `--javascript` option enables JavaScript support. @@ -110,8 +110,6 @@ The PDF will contain every page of type `pdf` that is referenced in the sidebars You can configure a single sidebar via `pdf_sidebar` or multiple sidebars via `pdf_sidebars`. E.g. if ```yml -pdf_sidebar: docs_sidebar - pdf_sidebars: - docs_sidebar diff --git a/pdfconfigs/config_docs_pdf.yml b/pdfconfigs/config_docs_pdf.yml index 7488961b59e..ed2c9207802 100644 --- a/pdfconfigs/config_docs_pdf.yml +++ b/pdfconfigs/config_docs_pdf.yml @@ -16,7 +16,7 @@ defaults: comments: true search: true -pdf_sidebar: docs_sidebar + pdf_sidebars: - docs_sidebar - tutorial_sidebar diff --git a/pdfconfigs/docs_part_title.html b/pdfconfigs/docs_part_title.html new file mode 100644 index 00000000000..29f9cb41e13 --- /dev/null +++ b/pdfconfigs/docs_part_title.html @@ -0,0 +1,8 @@ +--- +layout: page_print +permalink: docs_part_title.html +search: exclude +--- +
+

Part I: Documentation

+
\ No newline at end of file diff --git a/pdfconfigs/prince-list.txt b/pdfconfigs/prince-list.txt index 93ba686938d..9c773860f86 100644 --- a/pdfconfigs/prince-list.txt +++ b/pdfconfigs/prince-list.txt @@ -6,6 +6,8 @@ search: exclude {% assign docs_sidebar = site.data.sidebars.docs_sidebar.entries %} {% assign tutorial_sidebar = site.data.sidebars.tutorial_sidebar.entries %} +{{site.url}}{{site.baseurl}}/docs_part_title.html + {% for entry in docs_sidebar %} {% for folder in entry.folders %} {% if folder.output contains "pdf" %} @@ -14,11 +16,11 @@ search: exclude {{site.url}}{{site.baseurl}}{{folderitem.url}} {% for subfolders in folderitem.subfolders %} {% if subfolders.output contains "pdf" %} - {% for subfolderitem in subfolders.subfolderitems %} - {% if subfolderitem.output contains "pdf" %} - {{site.url}}{{site.baseurl}}{{subfolderitem.url}} - {% endif %} - {% endfor %} + {% for subfolderitem in subfolders.subfolderitems %} + {% if subfolderitem.output contains "pdf" %} + {{site.url}}{{site.baseurl}}{{subfolderitem.url}} + {% endif %} + {% endfor %} {% endif %} {% endfor %} {% endif %} @@ -27,6 +29,8 @@ search: exclude {% endfor %} {% endfor %} +{{site.url}}{{site.baseurl}}/tutorials_part_title.html + {% for entry in tutorial_sidebar %} {% for folder in entry.folders %} {% if folder.output contains "web" %} @@ -35,11 +39,11 @@ search: exclude {{site.url}}{{site.baseurl}}{{folderitem.url}} {% for subfolders in folderitem.subfolders %} {% if subfolders.output contains "web" %} - {% for subfolderitem in subfolders.subfolderitems %} - {% if subfolderitem.output contains "web" %} - {{site.url}}{{site.baseurl}}{{subfolderitem.url}} - {% endif %} - {% endfor %} + {% for subfolderitem in subfolders.subfolderitems %} + {% if subfolderitem.output contains "web" %} + {{site.url}}{{site.baseurl}}{{subfolderitem.url}} + {% endif %} + {% endfor %} {% endif %} {% endfor %} {% endif %} @@ -98,4 +102,4 @@ search: exclude {% endif %} {% endfor %} {% endfor %} -{% endcomment %} +{% endcomment %} \ No newline at end of file diff --git a/pdfconfigs/tocpage.html b/pdfconfigs/tocpage.html index 45bfc7e7e82..ca0216e8307 100644 --- a/pdfconfigs/tocpage.html +++ b/pdfconfigs/tocpage.html @@ -4,14 +4,16 @@ permalink: tocpage.html --- - + \ No newline at end of file diff --git a/pdfconfigs/tutorials_part_title.html b/pdfconfigs/tutorials_part_title.html new file mode 100644 index 00000000000..0b015ac790c --- /dev/null +++ b/pdfconfigs/tutorials_part_title.html @@ -0,0 +1,8 @@ +--- +layout: page_print +permalink: tutorials_part_title.html +search: exclude +--- +
+

Part II: Tutorials

+
\ No newline at end of file