Skip to content

Feature : tutorials to pdf #734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
the-matrixneo wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Feature : tutorials to pdf #734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
efe296d
feat: include tutorials in PDF and optimize file size
the-matrixneo Feb 22, 2026
5d60aec
Fix PDF sidebar config and add separators
the-matrixneo Mar 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions content/docs/docs-meta/docs-meta-publish-to-pdf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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-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.
Expand Down Expand Up @@ -106,10 +106,14 @@ 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
Expand All @@ -130,6 +134,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
Expand Down
3 changes: 1 addition & 2 deletions pdf-docs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
5 changes: 4 additions & 1 deletion pdfconfigs/config_docs_pdf.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,7 @@ defaults:
comments: true
search: true

pdf_sidebar: docs_sidebar

pdf_sidebars:
- docs_sidebar
- tutorial_sidebar
8 changes: 8 additions & 0 deletions pdfconfigs/docs_part_title.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
layout: page_print
permalink: docs_part_title.html
search: exclude
---
<div style="text-align: center; margin-top: 35vh; page-break-before: always;">
<h1 style="font-size: 3.5em; font-weight: bold;">Part I: Documentation</h1>
</div>
65 changes: 45 additions & 20 deletions pdfconfigs/prince-list.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,28 +3,53 @@ 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 %}
{{site.url}}{{site.baseurl}}/docs_part_title.html

{% 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 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 %}
{% endif %}
{% endfor %}
{% endfor %}
{% endif %}
{% endfor %}
{% endif %}
{% 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" %}
{% 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 %}
{% endfor %}


Expand Down Expand Up @@ -77,4 +102,4 @@ search: exclude
{% endif %}
{% endfor %}
{% endfor %}
{% endcomment %}
{% endcomment %}
103 changes: 69 additions & 34 deletions pdfconfigs/tocpage.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,41 +4,76 @@
permalink: tocpage.html
---

<!-- new page -->
<div id="navig">
<h1>Table of Contents</h1>

{% 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 %}

<ul id="mysidebar" class="nav">
{% for entry in sidebar %}
{% for folder in entry.folders %}
{% if folder.output contains "pdf" and folder.type != "frontmatter" %}
<li class="sectionHead">{{ folder.title }}
<ul>
{% for folderitem in folder.folderitems %}
{% if folderitem.output contains "pdf" and folderitem.type != "frontmatter"%}
<li><a href="{{folderitem.url | prepend: site.baseurl}}">{{folderitem.title}}</a>
{% for subfolders in folderitem.subfolders %}
{% if subfolders.output contains "pdf" and subfolders.type != "frontmatter" %}
<li class="subSectionHead"><span>{{ subfolders.title }}</span>
<ul>
{% for subfolderitem in subfolders.subfolderitems%}
{% if subfolderitem.output contains "pdf" and subfolderitem.type != "frontmatter"%}
<li><a href="{{subfolderitem.url | prepend: site.baseurl}}">{{subfolderitem.title}}</a></li>
{% endif %}
{% endfor %}
</ul>
</li>
{% endif %}
{% endfor %}
</li>
{% endif %}
{% endfor %}
</ul>
</li>
{% endif %}
{% endfor %}
{% endfor %}
</ul>
</div>
<ul id="mysidebar" class="nav">

<h2 style="margin-top: 20px; padding-bottom: 5px; border-bottom: 1px solid #ccc;">Documentation</h2>

{% for entry in docs_sidebar %}
{% for folder in entry.folders %}
{% if folder.output contains "pdf" and folder.type != "frontmatter" %}
<li class="sectionHead">{{ folder.title }}
<ul>
{% for folderitem in folder.folderitems %}
{% if folderitem.output contains "pdf" and folderitem.type != "frontmatter"%}
<li><a href="{{folderitem.url | prepend: site.baseurl}}">{{folderitem.title}}</a>
{% for subfolders in folderitem.subfolders %}
{% if subfolders.output contains "pdf" and subfolders.type != "frontmatter" %}
<li class="subSectionHead"><span>{{ subfolders.title }}</span>
<ul>
{% for subfolderitem in subfolders.subfolderitems%}
{% if subfolderitem.output contains "pdf" and subfolderitem.type != "frontmatter"%}
<li><a href="{{subfolderitem.url | prepend: site.baseurl}}">{{subfolderitem.title}}</a></li>
{% endif %}
{% endfor %}
</ul>
</li>
{% endif %}
{% endfor %}
</li>
{% endif %}
{% endfor %}
</ul>
</li>
{% endif %}
{% endfor %}
{% endfor %}

<h2 style="margin-top: 30px; padding-bottom: 5px; border-bottom: 1px solid #ccc;">Tutorials</h2>

{% for entry in tutorial_sidebar %}
Copy link
Member

@MakisH MakisH Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before the Docs and before the Tutorials, some part separator is needed. Right now, all sections are rendered the one after the other, as if Docs and Tutorials are in the same part.

{% for folder in entry.folders %}
{% if folder.output contains "web" and folder.type != "frontmatter" %}
<li class="sectionHead">{{ folder.title }}
<ul>
{% for folderitem in folder.folderitems %}
{% if folderitem.output contains "web" and folderitem.type != "frontmatter"%}
<li><a href="{{folderitem.url | prepend: site.baseurl}}">{{folderitem.title}}</a>
{% for subfolders in folderitem.subfolders %}
{% if subfolders.output contains "web" and subfolders.type != "frontmatter" %}
<li class="subSectionHead"><span>{{ subfolders.title }}</span>
<ul>
{% for subfolderitem in subfolders.subfolderitems%}
{% if subfolderitem.output contains "web" and subfolderitem.type != "frontmatter"%}
<li><a href="{{subfolderitem.url | prepend: site.baseurl}}">{{subfolderitem.title}}</a></li>
{% endif %}
{% endfor %}
</ul>
</li>
{% endif %}
{% endfor %}
</li>
{% endif %}
{% endfor %}
</ul>
</li>
{% endif %}
{% endfor %}
{% endfor %}
</ul>
</div>
8 changes: 8 additions & 0 deletions pdfconfigs/tutorials_part_title.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
layout: page_print
permalink: tutorials_part_title.html
search: exclude
---
<div style="text-align: center; margin-top: 35vh; page-break-before: always;">
<h1 style="font-size: 3.5em; font-weight: bold;">Part II: Tutorials</h1>
</div>