PDF Generation

.gitignore

@@ -4,7 +4,8 @@
 # Production
 /build
 
-# Generated files
+# Generated files and folders
+/pdf
 .docusaurus
 .cache-loader
 

README.md

@@ -38,7 +38,7 @@ The used framework to generate docs is [docusaurus](https://docusaurus.io).
 In order to not break links of posts, blog articles and shared documents we want to provide full backwards-compatibility.
 This means we need to ensure existing links still work with the new documentation.
 
-The file /static/_redirects contains a list of all paths of the old docs-sites. The file is formatted to create server-side-redirects on netlify, following the documentation here: https://docs.netlify.com/routing/redirects/
+The file /static/\_redirects contains a list of all paths of the old docs-sites. The file is formatted to create server-side-redirects on netlify, following the documentation here: https://docs.netlify.com/routing/redirects/
 
 ## Docs
 
@@ -95,43 +95,84 @@ tags:
 
 <YOUR ARTICLE>
 ```
+
 ## Setup & Build
+
 Reqires Bun as .js runtime.
 
 Run the following command to install dependencies:
+
 ```
 bun install
 ```
 
 To generate a local preview use:
+
 ```
 bun run start
 ```
 
 To update the dependencies for the Reference pages:
+
 ```
 bun run fetch-readmes
 ```
+
 ## Component references
-Ensure first, that all files in the docs folder are updated and ready to freeze. Also execute `bun run fetch-readmes` to update files from components and apis. 
+
+Ensure first, that all files in the docs folder are updated and ready to freeze. Also execute `bun run fetch-readmes` to update files from components and apis.
 All components are referenced in the `/scripts/components.json` file. Use this minimal template to add a new component:
+
 ```json
 {
         "name": "metalctl", // name of the component, will appear in the navigation
         "releasePath": "binaries.metal-stack.metalctl.version", // json-path of the version or tag in the release-vector
-        "repo": "metal-stack/metalctl", // component repository, 
+        "repo": "metal-stack/metalctl", // component repository,
         "position": 1, // use this property to sort the navigation subdirectories
         "withDocs": true // set to true to retrieve further .md files from a /docs folder. With false, only the README.md will be retrieved.
 },
 ```
+
 The `tag` property will be updated automatically from the release-vector file.
+
 ## Document Versioning
+
 You create a new version with:
+
 ```
 bun run docusaurus docs:version v0.21.6
 ```
+
 Now, the new version will be create and the latest files will be copied to the "`versioned`" folders.
 
+## PDF Generation
+
+For now we have different pdf-generation approaches:
+
+- typst
+- pupeteer
+- [docusuraus-plugin](https://github.com/jean-humann/docs-to-pdf)
+
+### Docusaurus Plugin
+
+The approach:
+
+- reference first doc-page
+- plugin crawls through docs by using "Next"-Button
+- gathers all rendered pages
+- generates based on this a html and then a pdf
+
+In order to stop split the pdf we have two options:
+
+- `excludePaths` parameter: still every sub-url gets visited
+- disable "Next"-Button on last section of page/pdf
+
+Command to test:
+
+```sh
+npx docs-to-pdf --initialDocURLs="http://localhost:3000/docs/introduction" --contentSelector="article" --paginationSelector="a.pagination-nav__link.pagination-nav__link--next" --excludeSelectors=".margin-vert--xl a,[class^='tocCollapsible'],.breadcrumbs,.theme-edit-this-page" --coverImage="https://metal-stack.io/v1.0_metalstack_io_logo_RGB_combination_mark_for_black.svg" --coverTitle="Metal-Stack Documentation" --cssStyle="body{font-size: 10px}"
+```
+
 ## Comparison
 
 ### Benefits

docs/docs/06-For Users/01-client_libraries.md

@@ -1,6 +1,7 @@
 ---
 slug: /client-libraries
 title: Client Libraries
+pagination_next: null
 sidebar_position: 1
 ---
 

docu.typ

@@ -0,0 +1,36 @@
+#import "@preview/cmarker:0.1.6"
+
+#set text(
+  size: 10pt,
+  font: ("inter")
+)
+
+= Metal-Stack Documentation
+
+#pagebreak()
+
+#outline(indent: auto, depth: 2)
+
+#pagebreak()
+
+#cmarker.render(read("./docs/docs/01-introduction.md"))
+#cmarker.render(read("./docs/docs/02-quickstart.md"))
+
+= Concepts
+#cmarker.render(read("./docs/docs/03-Concepts/architecture.md"), h1-level: 2,
+  scope: (image: (path, alt: none) => image("docs/docs/03-Concepts/" + path, alt: alt)))
+#cmarker.render(read("./docs/docs/03-Concepts/networking.md"), h1-level: 2,
+  scope: (image: (path, alt: none) => image("docs/docs/03-Concepts/" + path, alt: alt)))
+#cmarker.render(read("./docs/docs/03-Concepts/kubernetes.md"), h1-level: 2)
+#cmarker.render(read("./docs/docs/03-Concepts/isolated-kubernetes.md"), h1-level: 2,
+  scope: (image: (path, alt: none) => image("docs/docs/03-Concepts/" + path, alt: alt)))
+
+
+#cmarker.render(read("./docs/docs/03-Concepts/comparison.md"), h1-level: 2)
+
+= For Operators
+
+
+= For Users
+
+= Release Notes

docusaurus-pdf.config.ts

@@ -0,0 +1,105 @@
+import { themes as prismThemes } from "prism-react-renderer";
+import type { Config } from "@docusaurus/types";
+import type * as Preset from "@docusaurus/preset-classic";
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
+const commonDocsOptions = {
+  breadcrumbs: false,
+  showLastUpdateAuthor: false,
+  showLastUpdateTime: true,
+};
+
+const image_url = {
+  "Gerrit Schwerthelm": "https://github.com/gerrit91.png",
+  valentin: "https://github.com/vknabel.png",
+  stefan: "https://github.com/majst01.png",
+  markus: "https://github.com/mwindower.png",
+  grigoriy: "https://github.com/GrigoriyMikhalkin.png",
+};
+
+const config: Config = {
+  title: "metal-stack docs",
+  tagline: "Docs for metal-stack.",
+  favicon: "img/favicon.ico",
+
+  // Set the production url of your site here
+  url: "https://your-docusaurus-site.example.com",
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: "/",
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: "metal-stack", // Usually your GitHub org/user name.
+  projectName: "docs-new", // Usually your repo name.
+
+  onBrokenLinks: "warn",
+  onBrokenMarkdownLinks: "warn",
+
+  // Even if you don't use internationalization, you can use this field to set
+  // useful metadata like html lang. For example, if your site is Chinese, you
+  // may want to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en"],
+  },
+
+  markdown: {
+    format: "detect",
+  },
+
+  plugins: [["./src/plugins/tailwind-config.js", {}]],
+
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          // sidebarPath: "./sidebars.ts",
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          // editUrl:
+          //  "https://github.com/metal-stack/docs-new/tree/main/",
+        },
+        theme: {
+          customCss: "./src/css/custom.css",
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    colorMode: {
+      respectPrefersColorScheme: true,
+    },
+    // Replace with your project's social card
+    image: "img/metal-stack.png",
+    navbar: {
+      title: "metal-stack",
+      logo: {
+        alt: "metal-stack-log",
+        src: "img/metal-stack.png",
+      },
+      items: [
+        { type: "docsVersionDropdown" },
+        {
+          type: "doc",
+          label: "Docs",
+          position: "left",
+          docId: "docs/introduction",
+        }
+      ],
+    },
+    footer: {
+      style: "dark",
+      links: []
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;