diff --git a/.gitignore b/.gitignore index 7b8b3d8..f8c2b5e 100644 --- a/.gitignore +++ b/.gitignore @@ -6,12 +6,14 @@ temp/ ## main build output main.pdf chapter/out.tex +chapter/out.md ## IDE and Editor files .idea/** *.iml .sublime-project .sublime-workspace +.vscode/tasks.json ## MS Office Temp Files ~$*.ppt* diff --git a/.vscode/tasks.json b/.vscode/tasks.json deleted file mode 100644 index d6c252c..0000000 --- a/.vscode/tasks.json +++ /dev/null @@ -1,33 +0,0 @@ -{ - // See https://go.microsoft.com/fwlink/?LinkId=733558 - // for the documentation about the tasks.json format - "version": "2.0.0", - "tasks": [ - { - "label": "latexmk", - "type": "shell", - "command": "latexmk -latexoption=\"-shell-escape\" main.tex", - "group": { - "kind": "build", - "isDefault": true - }, - "dependsOrder": "sequence", - "dependsOn": ["clean"] - }, - { - "label": "clean", - "type": "shell", - "command": "latexmk -C; if [ -f chapter/out.tex ]; then rm chapter/out.tex; fi" - }, - { - "label": "pandoc", - "type": "shell", - "command": [ - "pandoc --filter pandoc-crossref --filter pandoc-citeproc ", - "-M cref=true --top-level-division=chapter ", - "--bibliography library/library.bib --biblatex ", - "-o chapter/out.tex chapter/*.md" - ] - } - ] -} \ No newline at end of file diff --git a/README.md b/README.md index 9f090f9..9209705 100644 --- a/README.md +++ b/README.md @@ -25,14 +25,20 @@ git pull boilerplate master git remote remove boilerplate ``` -In order to use the preconfigured CI / CD pipeline for building PDFs, copy either `latex.gitlab-ci.yml` or `markdown.gitlab-ci.yml` to `.gitlab-ci`, depending on which workflow you want to use. -On GitLab.com, this will use Dockerized builds by default. -If you want to use the workflow on own hardware, make sure your GitLab CI meets the [Basic Requirements](https://gitlab.com/fastexitlane/latex-boilerplate/wikis/GitLab-CI#basic-requirements). +In order to setup the repo for CI / CD on GitLab and Azurre DevOps, as well as VS Code integration, run `setup.sh latex` or `setup.sh markdown`, depending in which workflow you want to use. +CI will use Dockerized builds by default. +If you want to use the workflow on GitLab, but with own hardware, make sure your GitLab CI meets the [Basic Requirements](https://gitlab.com/fastexitlane/latex-boilerplate/wikis/GitLab-CI#basic-requirements). If you know what you're doing, simply start adding your content files in `chapter/` as LaTex `\chapter`s and `\input` them into `main.tex`. +You can then run the build using VS Code preconfigured tasks or using `build.sh`. + +For Markdown, add your content as `*.md` files in `chapter/` and prefix them with ascending numbers (to keep chapter sequence). +You shouldn't need to `\input` or configure anything else, as the files are concatenated automatically at build time. +Run `build.sh pandoc` to build your PDF. + If you do not know what you're doing or get into trouble - or want to use the **Markdown Workflow**, you may want to consider the [wiki](https://gitlab.com/fastexitlane/latex-boilerplate/wikis/home) ;-) ## Docker Images If you need a Docker image to build your documents, head over to [pandoc-latex](https://github.com/fastexitlane/pandoc-latex) ([DockerHub](https://hub.docker.com/r/fastexitlane/pandoc-latex)). -Also, there's a prebuilt Docker image for spellchecking using Hunspell - head over to [docker-hunspell](https://github.com/fastexitlane/docker-hunspell). \ No newline at end of file +Also, there's a prebuilt Docker image for spellchecking using Hunspell - head over to [docker-hunspell](https://github.com/fastexitlane/docker-hunspell). diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..6a49098 --- /dev/null +++ b/build.sh @@ -0,0 +1,25 @@ +#!/bin/bash + +# cleanup +latexmk -C +if [ -f chapter/out.tex ] +then + rm chapter/out.md + rm chapter/out.tex +fi + +# run pandoc +if [ $1 == "pandoc"] +then + cat chapter/*.md > chapter/out.md + pandoc --filter pandoc-citeproc --filter pandoc-crossref \ + -M cref=true --top-level-division=chapter \ + --bibliography library/library.bib --biblatex \ + -o chapter/out.tex chapter/out.md +fi + +# run latex build +if [ $1 != "clean" ] +then + latexmk -latexoption="-shell-escape" main.tex +fi diff --git a/config.tex b/config.tex index ccc2d49..f9c2acd 100644 --- a/config.tex +++ b/config.tex @@ -201,3 +201,7 @@ % Verbessert das Referenzieren von Kapiteln, Abbildungen etc. \usepackage[german,capitalise]{cleveref} + +% Pandoc Integration +\providecommand{\tightlist}{% + \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} diff --git a/setup.sh b/setup.sh new file mode 100755 index 0000000..4066f4c --- /dev/null +++ b/setup.sh @@ -0,0 +1,28 @@ +#!/bin/bash + +function write_help { + echo "Usage:" + echo " ./setup.sh markdown Setup Boilerplate for usage with Markdown" + echo " ./setup.sh latex Setup Boilerplate for usage with LaTex" +} + +if [ $# == 0 ] +then + write_help + exit 1 +fi + +if [ $1 == "markdown" ] +then + cp templates/markdown.gitlab-ci.yml ./.gitlab-ci.yml + cp templates/markdown.azure-pipelines.yml ./azure-pipelines.yml + cp templates/markdown.tasks.json ./.vscode/tasks.json + cp templates/markdown.main.tex ./main.tex +elif [ $1 == "latex" ] +then + cp templates/latex.gitlab-ci.yml ./.gitlab-ci.yml + cp templates/latex.azure-pipelines.yml ./azure-pipelines.yml + cp templates/latex.tasks.json ./.vscode/tasks.json +else + write_help +fi diff --git a/latex.azure-pipelines.yml b/templates/latex.azure-pipelines.yml similarity index 93% rename from latex.azure-pipelines.yml rename to templates/latex.azure-pipelines.yml index e273160..2be1a88 100644 --- a/latex.azure-pipelines.yml +++ b/templates/latex.azure-pipelines.yml @@ -23,8 +23,8 @@ stages: - job: latexmk container: fastexitlane/pandoc-latex:latest steps: - - script: latexmk main.tex - displayName: Execute LaTex Build + - script: ./build.sh + displayName: Run Build Script - task: PublishBuildArtifacts@1 inputs: ArtifactName: main.pdf diff --git a/latex.gitlab-ci.yml b/templates/latex.gitlab-ci.yml similarity index 97% rename from latex.gitlab-ci.yml rename to templates/latex.gitlab-ci.yml index 72ed292..64e09fc 100644 --- a/latex.gitlab-ci.yml +++ b/templates/latex.gitlab-ci.yml @@ -10,7 +10,7 @@ latexmk: - main*.pdf expire_in: 2d script: - - latexmk main.tex + - ./build.sh - ci_commit_sha_short=`git rev-parse --short $CI_COMMIT_SHA` - mv main.pdf main@$ci_commit_sha_short.pdf diff --git a/templates/latex.tasks.json b/templates/latex.tasks.json new file mode 100644 index 0000000..5c95be7 --- /dev/null +++ b/templates/latex.tasks.json @@ -0,0 +1,24 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "latexmk", + "type": "shell", + "command": "${workspaceFolder}/build.sh", + "group": { + "kind": "build", + "isDefault": true + }, + "dependsOrder": "sequence", + "dependsOn": ["clean"] + }, + { + "label": "clean", + "type": "shell", + "command": "${workspaceFolder}/build.sh clean", + "group": "none", + } + ] +} \ No newline at end of file diff --git a/markdown.azure-pipelines.yml b/templates/markdown.azure-pipelines.yml similarity index 75% rename from markdown.azure-pipelines.yml rename to templates/markdown.azure-pipelines.yml index b3fc7d2..2333265 100644 --- a/markdown.azure-pipelines.yml +++ b/templates/markdown.azure-pipelines.yml @@ -22,10 +22,8 @@ stages: jobs: - job: pandoc_latexmk steps: - - script: pandoc --filter pandoc-crossref --filter pandoc-citeproc -M cref=true --top-level-division=chapter --bibliography library/library.bib --biblatex -o chapter/out.tex chapter/*.md - displayName: Convert Markdown Files to LaTex - - script: latexmk main.tex - displayName: Execute LaTex Build + - script: ./build.sh pandoc + displayName: Run Build Script with Pandoc Option - task: PublishBuildArtifacts@1 inputs: ArtifactName: main.pdf diff --git a/markdown.gitlab-ci.yml b/templates/markdown.gitlab-ci.yml similarity index 82% rename from markdown.gitlab-ci.yml rename to templates/markdown.gitlab-ci.yml index 68de987..b7b5922 100644 --- a/markdown.gitlab-ci.yml +++ b/templates/markdown.gitlab-ci.yml @@ -11,8 +11,7 @@ pandoc_latexmk: - main*.pdf expire_in: 2d script: - - pandoc --filter pandoc-crossref --filter pandoc-citeproc -M cref=true --top-level-division=chapter --bibliography library/library.bib --biblatex -o chapter/out.tex chapter/*.md - - latexmk main.tex + - ./build.sh pandoc - ci_commit_sha_short=`git rev-parse --short $CI_COMMIT_SHA` - mv main.pdf main@$ci_commit_sha_short.pdf diff --git a/templates/markdown.main.tex b/templates/markdown.main.tex new file mode 100644 index 0000000..bd6ae1e --- /dev/null +++ b/templates/markdown.main.tex @@ -0,0 +1,80 @@ +% Makros +\newcommand{\dokumententyp}{Dokumententyp} +\newcommand{\abgabedatum}{\today} +\newcommand{\ort}{Ort} +\newcommand{\dokumententitel}{Titel} +\newcommand{\dokumentenuntertitel}{Untertitel} +\newcommand{\dokumentenautor}{Autor} +\newcommand{\matrikelnr}{Matrikel-Nr.} +\newcommand{\dokumentenautoradresse}{Adresse} +\newcommand{\dokumentenpruefer}{Prüfer} +\newcommand{\studiengang}{Studiengang} +\newcommand{\studiengruppe}{Studiengruppe} +\newcommand{\institution}{Institution} + +% config +\input{config.tex} + +\begin{document} + %%%%%%%%%%%%%%%%%%%%%%%%% + %% document title page %% + %%%%%%%%%%%%%%%%%%%%%%%%% + \input{additionals/title.tex} + + %%%%%%%%%%%%% + %% indexes %% + %%%%%%%%%%%%% + \pagenumbering{Roman} + + % disclosure statement - uncomment if needed + % \input{additionals/disclosure.tex} + % \newpage + + % executive summary - uncomment if needed + % \input{additionals/executive_summary.tex} + % \newpage + + % table of contents + \tableofcontents + \newpage + + % acronyms + \input{additionals/acronyms.tex} + \newpage + + % list of figures + \listoffigures + \newpage + + % list of tables + \listoftables + \newpage + + % list of listings + \listoflistings + \newpage + + %%%%%%%%%%%%% + %% content %% + %%%%%%%%%%%%% + \pagenumbering{arabic} + + % when using pandoc workflow, we only need to include the build output + \input{chapter/out.tex} + \newpage + + %%%%%%%%%%%%% + %% closing %% + %%%%%%%%%%%%% + % list of references + \input{additionals/references.tex} + \newpage + + % appendix - uncomment if needed + % \input{appendix/appendix.tex} + % \newpage + + % affirmation + \input{additionals/affirmation.tex} + +\end{document} diff --git a/templates/markdown.tasks.json b/templates/markdown.tasks.json new file mode 100644 index 0000000..ecfae69 --- /dev/null +++ b/templates/markdown.tasks.json @@ -0,0 +1,24 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "latexmk", + "type": "shell", + "command": "${workspaceFolder}/build.sh pandoc", + "group": { + "kind": "build", + "isDefault": true + }, + "dependsOrder": "sequence", + "dependsOn": ["clean"] + }, + { + "label": "clean", + "type": "shell", + "command": "${workspaceFolder}/build.sh clean", + "group": "none", + } + ] +} \ No newline at end of file