@farberg/reveal-template 1.0.49 → 1.0.50

package/README.md

@@ -1,21 +1,65 @@
 # reveal-template
 
-## Installation
+This is a helper package to simplify the generation of reveal.js presentations using Markdown files only. It contains a set of (optional) reveal plugins to simplify the creation of lectures.
 
-Install using `npm install @farberg/reveal-template`
+It is primarily used by myself so it is quite opinionated and makes certains assumptions on the structure of the lecture. Markdown files should follow a certain naming pattern:
+- Single level: `00 - Introduction.md`, `01 - Bla.md`, etc.
+- Two level: `00 - Introduction.md`, `01 - Topic 1.md`, `01a - Sub-Topic 1.md`, `01b - Sub-Topic 1.md`, `02 - Topic 2`, etc.
+
+The resulting files can be published on any web server and do not require server-side components. Everything is rendered by the browser.
+
+## Requirements and Installation
+
+To use this project, [node.js and npm](https://nodejs.org) are required.
+
+Create a new lecture:
+- Create a new folder and initialize an empty node.js project (e.g., `npm init --yes`)
+- Add this package as a dependency (`npm i @farberg/reveal-template`)
+- Read the documentation below
 
 ## Usage
 
 1. Create a file `package.json` describing your presentation (e.g., [like this one)](docs/package.json).
-2. Create your Presentation in Markdown (`00 - Introduction.md` in the examples below, see <a href="docs/00 - Introduction.md">this file</a> for an example).
-3. Create an HTML file (e.g., index.html)
+2. Create an HTML file (e.g., `index.html`, see [npm.html](docs/npm.html) for an example)
+3. Create your presentation in [Markdown](https://en.wikipedia.org/wiki/Markdown)
+   - See <a href="docs/00 - Introduction.md">this file</a> for an example).
    - Using npm (`npm install @farberg/reveal-template`), see [npm.html](docs/npm.html) for an example.
-   - Using a CDN, see [cdn.html](docs/cdn.html) for an example ([see the published result here](https://pfisterer.github.io/reveal-template/cdn.html))
 
+## Plugins
+
+Click on the link for documentation
+
+*Tested and working* 
+
+| Name                                                                                   | Description                                                                                               |
+| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| [reveal-plugin-dir-tree.js](http://plugins/reveal-plugin-dir-tree.js)                  | Create a zip from existing files for download and display a tree of files                                 |
+| [reveal-plugin-html-example.js](plugins/reveal-plugin-html-example.js)                 | Renders a code example as innerHTML of a target element                                                   |
+| [reveal-plugin-prefix-with-base-url.js](plugins/reveal-plugin-prefix-with-base-url.js) | Prefixes the pages base URL to an element's inner Text. Optionally converts it to inline code.            |
+| [reveal-plugin-show-attribution.js](plugins/reveal-plugin-show-attribution.js)         | Shows credits on the lower right corner                                                                   |
+| [reveal-plugin-show-code-snippets.js](plugins/reveal-plugin-show-code-snippets.js)     | Shows a code snippet after loading it from a file.                                                        |
+| [reveal-plugin-show-qr-code.js](plugins/reveal-plugin-show-qr-code.js)                 | Display a QR code and link to the presentation on the slides slides                                       |
+| [reveal-plugin-show-title.js](plugins/reveal-plugin-show-title.js)                     | Create a title slide automatically                                                                        |
+| [reveal-plugin-show-toc.js](plugins/reveal-plugin-show-toc.js)                         | Create a table of contents automatically (run `npx dennis_generate_toc > generated_toc.html` to generate) |
+
+*Non-functional, untested or in development*
+
+| Name                                                                           | Description                                          |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| [reveal-plugin-modify-font-size.js](plugins/reveal-plugin-modify-font-size.js) | Add keybindings `+` and `-` to change base font size |
+| [reveal-plugin-toggle-solutions.js](plugins/reveal-plugin-toggle-solutions.js) | Show of hide solutions                               |
+
+## Conversion to PDF
+
+Run `npx dennis_generate_pdfs` to create PDFs. Requires a running [Docker](https://www.docker.com/) daemon.
 
 ## Local Development
 
-Check out this repository, run `npm install`, run a web server from the root directory, and open <http://localhost:5500/docs/local-dev.html>.
+To start developing on this repository:
+- Check out this repository (`git clone https://github.com/pfisterer/reveal-template.git`)
+- Run `npm install` to install required dependencies
+- Start a web server from the root directory (e.g., `npx http-server -p 5500`)
+- Open <http://localhost:5500/docs/local-dev.html>
 
 ## Publish a new version (maintainers only)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farberg/reveal-template",
-  "version": "1.0.49",
+  "version": "1.0.50",
   "homepage": "https://github.com/pfisterer/reveal-template",
   "description": "Reveal.js template for Dennis' lectures",
   "main": "index.js",
@@ -19,8 +19,8 @@
     "file-saver": "^2.0.5",
     "jszip": "^3.7.1",
     "qrcode": "^1.5.0",
-    "reveal.js": "^4.2.1",
+    "reveal.js": "^4.3.1",
     "reveal.js-plugins": "^4.1.5",
-    "serve-static": "^1.14.2"
+    "serve-static": "^1.15.0"
   }
 }

package/plugins/reveal-plugin-dir-tree.js

@@ -1,3 +1,21 @@
+/*
+Create a zip from existing files for download and display a tree of files
+
+<pre class="dirtree" data-zipname="k8s-Exercise.zip" data-strip-prefix="code/k8s-demo-app"> 
+code/k8s-demo-app/01-mariadb-deployment.yaml
+code/k8s-demo-app/02-k8s-mariadb-service.yaml
+code/k8s-demo-app/03-memcached-deployment-and-service.yaml
+code/k8s-demo-app/04-app-deployment-minikube.yaml
+code/k8s-demo-app/04-app-service-and-ingress.yaml
+code/k8s-demo-app/Dockerfile
+code/k8s-demo-app/package.json
+code/k8s-demo-app/server.js
+</pre>
+
+
+
+*/
+
 const dir_tree = {
 	id: 'dir_tree',
 	init: (deck) => {

package/plugins/reveal-plugin-html-example.js

@@ -1,3 +1,21 @@
+/*
+Renders a code example as innerHTML of a target element (default is the next sibling with class html-example-output)
+
+Parameters:
+- data-html-destination-id: change default destination element
+
+<h1>Willkommen im Internet</h1>
+```
+<!-- .element: data-html-example -->
+
+Output
+
+<div class="html-example-output"></div>
+
+
+*/
+
+
 function resizeIFrameToFitContent(iFrame) {
 	iFrame.width = iFrame.contentWindow.document.body.scrollWidth;
 	iFrame.height = iFrame.contentWindow.document.body.scrollHeight;

package/plugins/reveal-plugin-prefix-with-base-url.js

@@ -1,3 +1,14 @@
+/*
+Prefixes the pages base URL to an element's inner Text
+
+Parameters:
+- data-convert-to-inline-code="language": Converts the element to an inline code element.
+
+Example:
+
+<span data-prefix-url data-convert-to-inline-code="bash">code/k8s-simple/pod-demo-busybox.yaml</span>
+*/
+
 const dir_tree = {
 	id: 'prefix_url',
 	init: (deck) => {

package/plugins/reveal-plugin-show-attribution.js

@@ -1,3 +1,12 @@
+/*
+	Extracts data from the current slide's <credit></credit> innerHTML 
+	and inserts it into the global attribution element.
+
+	Example:
+		
+	<credits>Bildquelle: Some Page (<a href="https://example.com/photos/133434">example.com</a>)</credits>
+*/
+
 function showAttributionOnSlide(slide) {
 	//This will set the current credits correctly
 	var creditsTag = document.getElementById("attribution");

package/plugins/reveal-plugin-show-code-snippets.js

@@ -1,3 +1,21 @@
+/*
+Shows a code snippet after loading it from a file.
+
+Parameters:
+- data-code: Language
+- data-begin: Begin indicator in the file (optional)
+- data-end: End indicator in the file (optional)
+- data-link: Show a link to the file (optional)
+
+Example
+
+<a 	data-code='bash' 
+	data-begin="# Begin indicator in the file" 
+	data-end="# End indicator in the file" 
+	data-link
+	href="link/to/the/file.sh">Source code</a>
+*/
+
 import outdent from './outdent.js'
 
 function showError(el, err) {

package/plugins/reveal-plugin-show-qr-code.js

@@ -1,4 +1,22 @@
+/*
+	Display a QR code in a destination element by extracting data out of `package.json` and can show the URL on the slides
 
+	package.json:
+
+	{
+		[...]
+		"homepage": "http://the.url/to/the/slides"
+		[...]
+	}
+
+	Example:
+		Show QR code: 
+			<canvas class="qrcodeforslides"></canvas>
+
+		Show URL: 
+			<a class="urlforslides" style="font-size: 200%"></a>
+
+*/
 function showLinkToSlidesAndQrCode(deck, url) {
 	if (url === undefined)
 		return

package/plugins/reveal-plugin-show-title.js

@@ -1,3 +1,23 @@
+/*
+	Create a title slide automatically by reading data out of package.json to display the title slide:
+	
+	package.json:
+	
+	{
+		[...]
+		title: "Title of the presentation",
+		homepage: "https://the.url/to/the/slides",
+		authors: [
+			{ "name": "John Doe", homepage:"https://jon.doe.com" },
+			{ "name": "Jane Doe", homepage:"https://jane.doe.com" },
+		]
+		[...]
+	}
+
+	Example markdown:
+		<div class="lecturetitle">This is the Title of the Presentation</div>
+*/
+
 function showTitle(deck, packageJson) {
 	let lectureTitle = packageJson.title
 

package/plugins/reveal-plugin-show-toc.js

@@ -1,3 +1,18 @@
+/*
+	Loads the table of contents from a file and displays it
+
+	Parameters:
+
+		data-toc-src: Defaults to "generated_toc.html" 
+	
+	Example:
+
+	## Agenda
+	<!-- .slide: id="agenda" -->
+
+	<div data-toc-src="generated_toc.html" style="font-size: 0.82em;" />
+ */
+
 function showToc(url, el) {
 	fetch(url, { "cache": "no-store" })
 		.then(res => res.text())

package/docs/cdn.html

@@ -1,28 +0,0 @@
-<html>
-
-<head>
-	<meta charset="utf-8">
-	<meta name="apple-mobile-web-app-capable" content="yes" />
-	<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
-	<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=yes, minimal-ui">
-
-	<link rel="stylesheet" href="https://unpkg.com/reveal.js/dist/reveal.css">
-	<link rel="stylesheet" href="https://unpkg.com/reveal.js/plugin/highlight/zenburn.css">
-	<link rel="stylesheet" href="https://unpkg.com/@farberg/reveal-template/css/dhbw.css" id="theme">
-
-	<script type="module">
-		import { initReveal } from 'https://unpkg.com/@farberg/reveal-template/init-reveal.js'
-		const revealPath = "https://unpkg.com/reveal.js/"
-
-		initReveal({
-			indexDocument: "00 - Introduction.md",
-			revealPath: revealPath,
-		})
-	</script>
-</head>
-
-<body>
-	<div class="reveal">
-		<div class="slides"></div>
-	</div>
-</body>