Repository files navigation

Universal document publishing system.

Deliverance: The ship assigned to carryHari Seldon and his Foundation to colonize the planet Terminus

Deliverance is a minimal (a singleMakefile) digital publishing system that intents to make distributing self-contained documents, whether these are study notes, research papers, lab reports or even a bachelor's thesis, trivial. It has been in use for multiple years to create reports and study materials atMedia University Stuttgart.

It enables you to:

• Publish using Markdown: By using the well-supported Markdown format as its input language, Deliverance easily fits into your existing workflow.
• Support many output formats without complicated configuration: By default, Deliverance builds into many output formats at once - including PDF, HTML, EPUB, TXT, Gemini, ODT, DOCX, various slide formats and more!
• Create self-contained and reproducible documents: Deliverance creates fully self-contained and self-documenting outputs, including the full Git changelog, source repo URL, source code itself and more.
• Integrate with CI/CD systems: By using the Deliverance GitHub action, you can easily publish your documents to GitHub pages or other hosts.
• Use LaTeX and BibTeX features: Thanks to its internal use ofpandoc, Deliverance can be used for scientific publishing.

To make getting started with Deliverance easier, take a look at the following examples (or continue on toUsage):

• Scientific Publishing:
  • The SolarWinds Attack and Farm-to-table Methods in the Development Process: Mitigating disasters through supply chain security by Felicitas Pojtinger (Stuttgart Media University, 2022) (published document)
  • Efficient Synchronization of Linux Memory Regions over a Network: A Comparative Study and Implementation: A user‑friendly approach to application‑agnostic state synchronization by Felicitas Pojtinger (Stuttgart Media University, 2023) (published document)
• Study Materials:
  • uni-algodat-notes: Notes for the Anwendungssicherheit (app security) course at HdM Stuttgart (2022) (published document).
  • uni-appsecurity-notes: Notes for the Anwendungssicherheit (app security) course at HdM Stuttgart (2022) (published document).
  • uni-bwl-notes: Notes for the Planung und Kalkulation von IT-Projekten (econ 101) course at HdM Stuttgart (2021) (published document).
  • uni-db1-notes: Notes for the DB1 (databases) course at HdM Stuttgart (2021) (published document).
  • uni-distributedsystems-notes: Notes for the distributed systems course at HdM Stuttgart (2023) (published document).
  • uni-hacking-notes: Notes for the hacking (IT-Sicherheit: Angriff & Verteidigung) course at HdM Stuttgart (2022) (published document).
  • uni-itsec-notes: Notes for the IT security course at HdM Stuttgart (2022) (published document).
  • uni-programminglanguages-notes: Notes for the programming languages (Aktuelle Programmiersprachen) course at HdM Stuttgart (2023) (published document).
  • uni-sciwriting-notes: Notes for the Anleitung zum wissenschaftlichen Arbeiten (scientific writing) course at HdM Stuttgart (2021) (published document).
  • uni-webdev-backend-notes: Notes for the webdev backend course at HdM Stuttgart (2023) (published document).
  • uni-webtopics-notes: Notes for the Spezielle Themen für Web-Anwendungen (special topics for web applications) course at HdM Stuttgart (2022) (published document).
• Lab Reports:
  • uni-netpractice-notes: Notes for the Praktikum Rechnernetze (networking practice) course at HdM Stuttgart (2022) (published document).

TL;DR: Create aconfigure script, write your documents in Markdown, and publish to the web with the GitHub action

Prefer starting with an starter project? Check out theexamples!

First, create a new repository. On GitHub, you can do this by heading togithub.com/new, but you can also create a local repo usinggit init. After you've cloned or initialized your repo, create theconfigure script in it and make it executable:

$ tee> configure<<EOT#!/bin/shcurl -LO https://github.com/pojntfx/deliverance/releases/latest/download/MakefileEOT$ chmod +x configure$ tee> .gitgnore<<EOToutMakefileEOT

Once you've done that, you can use it to download the latest DeliveranceMakefile and download the dependencies:

$ ./configure$ make depend

Now, add aLICENSE file, aREADME.md etc. - you can find examples for this inexamples.

Your Markdown documents should be in thedocs folder; you can put any static assets, such as pictures, references or quotation styles, intostatic/docs - for example, you can start with this document indocs/main.md:

---author:[Felicitas Pojtinger]date:"2023-01-28"subject:"Uni Webdev Backend Summary"keywords:[webdev-backend, hdm-stuttgart]subtitle:"Summary for the webdev backend course at HdM Stuttgart"lang:"de"---#Uni Webdev Backend Summary##Meta###ContributingThese study materials are heavily based on[professor Toenniessen's "Web Development Backend" lecture at HdM Stuttgart](https://www.hdm-stuttgart.de/bibliothek/studieninteressierte/bachelor/block?sgname=Mobile+Medien+%28Bachelor%2C+7+Semester%29&sgblockID=2573378&sgang=550041&blockname=Web+Development+Backend) and prior work of fellow students.**Found an error or have a suggestion?** Please open an issue on GitHub ([github.com/pojntfx/uni-webdev-backend-notes](https://github.com/pojntfx/uni-webdev-backend-notes)):![QR code to source repository](./static/qr.png){ width=150px }If you like the study materials, a GitHub star is always appreciated :)###License![AGPL-3.0 license badge](https://www.gnu.org/graphics/agplv3-155x51.png){ width=128px }Uni Webdev Backend Notes (c) 2023 Felicitas Pojtinger and contributorsSPDX-License-Identifier: AGPL-3.0\newpage##Themen der Vorlesung1.**Einführung in Node.js** und einfache HTML-Fileserver2.**RESTful Endpoints** mit Express.js3. Die Template-Engine**EJS** und**Express-Sessions**4. Datenbanken mit**MongoDB und Mongoose**

Depending on the type of document you want to write, you might also benefit from including an abstract, bibliography or more - you can find examples for this inexamples.

Once you've added your starter document (you can also add multiple ones), you can start iterating on it by runningmake dev-pdf/main - this will start compiling your notes to a PDF file on each change. You can then usemake open-pdf/main to open the PDF file, or iterate on one of the other formats by usingmake dev-html/main,make dev-txt/main - there are many othermake targets available as well, so be sure to check these out withmake <tab>.

To publish to the web, you can either runmake and upload theout/release.tar.gz archive to your web server of choice, or use the provided GitHub action by adding the following to.github/deliverance.yaml:

name:Deliverance CIon:push:pull_request:schedule:    -cron:"0 0 * * 0"jobs:build-linux:runs-on:ubuntu-lateststeps:      -name:Checkout, build and publish with Deliveranceuses:pojntfx/deliverance@latestwith:github_token:"${{ secrets.GITHUB_TOKEN }}"

After you've added this file, push to your repo, enable GitHub pages for thegh-pages branch and your documents should be accessible to everyone with an internet connection. Here is an example of a published document:uni-supply-chain-paper

🚀 You're all set to publish your documents! We can't wait to see what you're going to share with Deliverance.

• pandoc does most of the heavy lifting by providing the file conversion capabilities.
• Eisvogel provides the LaTeX template for PDF outputs.
• makew0rld/md2gemini enables the Markdown to Gemini conversion.

To contribute, please use theGitHub flow and follow ourCode of Conduct.

Have any questions or need help? Chat with uson Matrix!

Deliverance (c) 2024 Felicitas Pojtinger and contributors

SPDX-License-Identifier: AGPL-3.0