basic-report:0.3.1

packages/preview/basic-report/0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Roland Schätzle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/preview/basic-report/0.3.1/README.md

@@ -0,0 +1,67 @@
+# Basic Report
+
+A [Typst](https://typst.app/home/) template for shorter non-fiction documents like reports, manuals, requirements documentation, student assignments etc. An example document (PDF) that shows how it looks like, can be found [here](https://github.com/roland-KA/basic-report-typst-template/blob/main/examples/main.pdf).
+
+The template comes without bells and whistles and consists just of
+- a titlepage with
+    - logo
+    - title & document category
+    - info block (date, author, affiliation)
+- the TOC 
+- and then the contents (with currently three levels of headings)
+
+The TOC uses roman page numbers, the rest of the document arabic numbers.
+
+For documents with only a few pages there is often no need for an outline and a separate title page. For these documents there is a `compact-mode`, where title information is shown on the first text page. An example for this mode can be found [here](https://github.com/roland-KA/basic-report-typst-template/blob/main/examples/mainCompact.pdf)
+
+## Usage
+
+You can use this template in the Typst web app by clicking "Start from template" on the dashboard and searching for `basic-report`.
+
+Alternatively, you can use the CLI to kick this project off using the command
+
+```shell
+typst init @preview/basic-report
+```
+
+Typst will create a new directory with all the files needed to get you started.
+
+## Fonts
+
+ _**Vollkorn**_ is used for the body text. It's a high quality font for long texts designed by [Friedrich Althausen](http://friedrichalthausen.de/). It was one of the first Google Fonts. But I recommend to download it from the designers [project web page](http://vollkorn-typeface.com/), because that variant has the small caps font included (on [Google Fonts](https://fonts.google.com/specimen/Vollkorn) that's a separate font). The online version of Typst has Vollkorn preinstalled.
+
+ In it's current version it's an extensive font with 12 styles as well as true small caps, a variety of localisations, a complete set of figures (proportional/tabular, lining/old style, small caps), many ligatures etc.
+
+ [_**Ubuntu**_](https://design.ubuntu.com/font) is the contrasting companion for headings, labels, the header, the titlepage etc. Designed by [Dalton Maag](https://www.daltonmaag.com/) it adds a contemporary touch with its own personality. Ubuntu is available via [Google Fonts](https://fonts.google.com/specimen/Ubuntu).
+
+ As the heading font can be changed using the parameter `heading-font` other variants can be used as well. The following fonts are good pairings with the body font Vollkorn and have been tested with the template:
+
+ - **Lato** is a bit more elegant than Ubuntu
+ - **Fira Sans** or **Source Sans Pro** can be used, if a more neutral appearance is desired (Note: The newer version of _Source Sans Pro_, named "Source Sans 3" has in some cases other default measures which do not work well with the template).
+
+All three recommendations are pre-installed in the online version of Typst. If you want to use them on your local computer, you can get them from Google Fonts.
+
+
+
+
+## Packages Used
+
+The [Hydra package](https://github.com/tingerrr/hydra) is used to display the current heading within the header.
+
+
+## Configuration
+
+The template exports one function `basic-report` with the following named parameters:
+
+-  `doc-category (str)`:  The documents category (e.g. "User Manual", "Lab Report", "Monthly Review")
+-  `doc-title (str)`: The documents title
+-  `author (str)`: The author; if there are several authors, they can just be listed within one string argument.
+-  `affiliation (str)`: Organisation/Company etc.
+-  `logo (image)`: an `image` (usage: e.g. `image("path/to/image.svg")`)
+-  `language (str)`: Language of the document (default is "de")
+-  `show-outline (boolean)`: Show the outline (default is `true`)
+-  `compact-mode (boolean)`: If true, there is no TOC and no separate title page. All title information is displayed on the first text page (default is `false`)
+-  `heading-color`: The color of the title and all headings (default is `blue`)
+-  `heading-font`: The font used for the title and all headings (default is `"Ubuntu"`; recommended and tested alternatives are "Lato", "Fira Sans" or "Source Sans Pro")
+
+Have a look at the example file [`main.typ`](https://github.com/roland-KA/basic-report-typst-template/blob/main/template/main.typ) whithin the [`template`](https://github.com/roland-KA/basic-report-typst-template/tree/main/template) directory on how to use the `basic-report`-function with these parameters.

packages/preview/basic-report/0.3.1/lib.typ

@@ -0,0 +1,223 @@
+#import "@preview/hydra:0.6.2": hydra
+#import "titlepage.typ": *
+
+// ----- Main Template Function: `basic-report` ----------------------
+
+#let basic-report(
+  doc-category: none,
+  doc-title: none,
+  author: none,
+  affiliation: none,
+  logo: none,
+  language: "de",
+  show-outline: true,
+  compact-mode: false,
+  heading-color: blue,
+  heading-font: "Ubuntu", // recommended alternatives: "Fira Sans", "Lato", "Source Sans Pro"
+  body,
+) = {
+
+  // ----- Global Parameters ------------------------
+
+  set document(title: doc-title, author: author)
+  set text(lang: language)
+
+
+  let body-font = "Vollkorn"
+  let body-size = 11pt
+  // let heading-font = "Ubuntu"
+
+  // heading font is used in this size for kind of "information blocks"
+  let info-size = 10pt              
+
+  // heading font is used in this size for different sorts of labels            
+  let label-size = 9pt                          
+
+  // are we inside or outside of the outline (for roman/arabic page numbers)?
+  let in-outline = state("in-outline", if compact-mode {false} else {true})    
+
+  // ----- Title Page ------------------------
+
+  if (not compact-mode) {
+    counter(page).update(0)                     // so TOC after titlepage begins with page no 1 (roman)
+    titlepage(
+      doc-category,
+      doc-title,
+      author,
+      affiliation,
+      logo,
+      heading-font,
+      heading-color,
+      info-size,
+    )
+  } 
+
+  // ----- Basic Text- and Page-Setup ------------------------
+
+  set text(
+    font: body-font,
+    size: body-size,
+    // Vollkorn has a broader stroke than other fonts; in order to adapt the grey value (Grauwert)
+    // of the page the font gets printed in a dark grey (instead of completely black)
+    fill: luma(50)
+  )
+
+  set par(
+    justify: true,
+    leading: 0.75em,
+    spacing: 1.65em,
+    first-line-indent: 0em,
+  )
+
+  // Page Grid:
+  // Horizontal 1.5cm-grid = 14u: 3u left margin, 9u text, 2u right margin
+  //     Idea: one-sided document; if printed on paper, the pages are often bound or stapled
+  //     on the left side; so more space needed on the left. On-screen it doesn't matter.
+  // Vertical 1.5cm-grid ≈ 20u: 2u top margin, 14u text, 2u botttom margin
+  //     header with height ≈ 0.6cm is visually part of text block --> top margin = 3cm + 0.6cm
+  set page(               // standard page with header
+    paper: "a4",
+    margin: (top: 3.6cm, left: 4.5cm, right: 3cm, bottom: 3cm),
+    // the header shows the main chapter heading on the left and the page number on the right
+    header: context {
+      if compact-mode and (counter(page).get().first() == 1) {
+        none
+      } else {
+        grid(
+          columns: (1fr, 1fr),
+          align: (left, right),
+          row-gutter: 0.5em,
+          text(font: heading-font, size: label-size,
+            context {hydra(1, use-last: false, skip-starting: false)},),
+          text(font: heading-font, size: label-size, 
+            number-type: "lining",
+            context {if in-outline.get() {
+                counter(page).display("i")      // roman page numbers for the TOC
+              } else {
+                counter(page).display("1")      // arabic page numbers for the rest of the document
+              }
+            }
+          ),
+          grid.cell(colspan: 2, line(length: 100%, stroke: 0.5pt)),
+        )
+      }
+    },
+    header-ascent: 1.5em
+  )
+
+
+  // ----- Headings & Numbering Schemes ------------------------
+
+  set heading(numbering: "1.")
+  show heading: set text(font: heading-font, fill: heading-color, 
+      weight: if compact-mode {"bold"} else {"regular"})
+  show heading: set par(justify: false)
+
+
+  show heading.where(level: 1): it => {
+    v(3.8 * body-size, weak: true) + text(it) + v(0.2 * body-size)
+  }
+  show heading.where(level: 2): it => {
+    v(0.8 * body-size) + text(it) + v(0.2 * body-size)
+  }
+  show heading.where(level: 3): it => {
+    v(0.8 * body-size) + text(it) + v(0.2 * body-size)
+  }
+
+  set figure(numbering: "1")
+  show figure.caption: it => {
+    set text(font: heading-font, size: label-size)
+    block(it)
+  }
+
+  // ----- Table of Contents ------------------------
+
+  // to detect, if inside or outside the outline (for different page numbers)
+  show outline: it => {
+    in-outline.update(true)
+    it
+    in-outline.update(false)
+  }
+
+  // top-level TOC entries in bold without filling
+  show outline.entry.where(level: 1): it => {
+    set block(above: 2 * body-size)
+    set text(font: heading-font, weight: "bold", size: info-size)
+    link(
+      it.element.location(),    // make entry linkable
+      it.indented(it.prefix(), it.body() + box(width: 1fr,) +  strong(it.page()))
+    )
+  }
+
+  // other TOC entries in regular with adapted filling
+  show outline.entry.where(level: 2).or(outline.entry.where(level: 3)): it => {
+    set block(above: 0.8 * body-size)
+    set text(font: heading-font, size: info-size)
+    link(
+      it.element.location(),  // make entry linkable
+      it.indented(
+          it.prefix(),
+          it.body() + "  " +
+            box(width: 1fr, repeat([.], gap: 2pt)) +
+            "  " + it.page()
+      )
+    )
+  }
+
+  if (show-outline and not compact-mode) {
+    outline(
+      title: if language == "de" { 
+        "Inhalt"
+      } else if language == "fr" {
+        "Table des matières"
+      } else if language == "es" {
+        "Contenido"
+      } else if language == "it" {
+        "Indice"
+      } else if language == "nl" {
+        "Inhoud"
+      } else if language == "pt" {
+        "Índice"
+      } else if language == "zh" {
+        "目录"
+      } else if language == "ja" {
+        "目次"
+      } else if language == "ru" {
+        "Содержание"
+      } else if language == "ar" {
+        "المحتويات"
+      } else {
+        "Contents"
+      },
+      indent: auto,
+    )
+    counter(page).update(0)     // so the first chapter starts at page 1 (now in arabic numbers)
+  } else {
+    in-outline.update(false)    // even if outline is not shown, we want to continue with arabic page numbers
+    counter(page).update(1)
+  }
+
+  if (not compact-mode) {
+    pagebreak()
+  }
+
+  // ----- Body Text ------------------------
+
+  if compact-mode {             // compact title infos in compact-mode
+    compact-title(
+      doc-category,
+      doc-title,
+      author,
+      affiliation,
+      logo,
+      heading-font,             
+      heading-color,            
+      info-size,                
+      body-size,
+      label-size,
+    )
+  }
+
+  body
+
+}

packages/preview/basic-report/0.3.1/template/main.typ

@@ -0,0 +1,47 @@
+
+#import "@preview/basic-report:0.3.1": *
+
+#show: it => basic-report(
+  doc-category: "Betriebsanleitung",
+  doc-title: "Raketenstart für Dummies",
+  author: "Daniel Düsentrieb",
+  affiliation: "MouseTec, Entenhausen",
+  logo: image("assets/aerospace-engineering.png", width: 2cm),
+  // <a href="https://www.flaticon.com/free-icons/aerospace" title="aerospace icons">Aerospace icons created by gravisio - Flaticon</a>
+  language: "de",
+  compact-mode: true,
+  it
+)
+
+= Einleitung
+
+#lorem(120)
+
+#lorem(150)
+
+== Fluggeräte
+
+#lorem(100)
+
+=== Raketen – Eine Übersicht
+
+#lorem(80)
+
+= Dein erster Raketenstart
+
+#lorem(150)
+
+== Wie du in die Rakete einsteigst
+
+#lorem(90)
+
+== Das Cockpit
+
+#lorem(120)
+
+
+=== Die wichtigsten Knöpfe und Hebel
+
+#lorem(50)
+
+