{"id":7543119,"url":"https://github.com/periodicpoint/arabica","last_synced_at":"2025-05-10T15:32:10.665Z","repository":{"id":232099174,"uuid":"129888083","full_name":"periodicpoint/arabica","owner":"periodicpoint","description":"A sound and versatile pandoc LaTeX boilerplate to produce academic books using Markdown files featuring YAML, KOMA-Script, BibLaTeX and CSL","archived":false,"fork":false,"pushed_at":"2019-01-21T22:06:04.000Z","size":1598,"stargazers_count":73,"open_issues_count":2,"forks_count":7,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-16T21:33:13.021Z","etag":null,"topics":["academic","biblatex","boilerplate","book","csl","koma-script","latex","latex-template","markdown","pandoc","pandoc-boilerplate","pandoc-citeproc","pandoc-crossref","pandoc-template","pdf","publishing","typesetting","writing","xelatex","yaml"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/periodicpoint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-17T10:32:56.000Z","updated_at":"2024-01-11T17:47:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"740692ad-2faa-4a56-81f3-80c6bbd6e187","html_url":"https://github.com/periodicpoint/arabica","commit_stats":null,"previous_names":["periodicpoint/arabica"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/periodicpoint%2Farabica","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/periodicpoint%2Farabica/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/periodicpoint%2Farabica/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/periodicpoint%2Farabica/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/periodicpoint","download_url":"https://codeload.github.com/periodicpoint/arabica/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253436711,"owners_count":21908392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["academic","biblatex","boilerplate","book","csl","koma-script","latex","latex-template","markdown","pandoc","pandoc-boilerplate","pandoc-citeproc","pandoc-crossref","pandoc-template","pdf","publishing","typesetting","writing","xelatex","yaml"],"created_at":"2024-04-08T00:26:08.166Z","updated_at":"2025-05-10T15:32:10.648Z","avatar_url":"https://github.com/periodicpoint.png","language":null,"funding_links":[],"categories":["Templates and Guides"],"sub_categories":["Markdown"],"readme":"# arabica\nA sound and versatile [pandoc](http://pandoc.org/) [LaTeX](https://www.latex-project.org/) boilerplate to produce academic books (in PDF) utilising solely modular [Markdown](https://daringfireball.net/projects/markdown/) files, featuring\n[YAML](http://yaml.org/), [KOMA-Script](https://ctan.org/pkg/koma-script?lang=en), [BibLaTeX](https://ctan.org/pkg/biblatex?lang=en) and\n[CSL](http://citationstyles.org/).\n\nFor typesetting an **article** please see the\n[**robusta boilerplate**](https://github.com/qualiacode/robusta).\n\n# Thanks\nThe [*arabica boilerplate*](https://github.com/qualiacode/arabica) is inspired by the [pandoc latex template *eisvogel* by Wandmalfarbe](https://github.com/Wandmalfarbe/pandoc-latex-template) and was built with the help of the following sources and tools: [References and Credits](#references-and-credits).\nFor other projects like the one at hand please see [the list of user contributed templates at the pandoc wiki](https://github.com/jgm/pandoc/wiki/User-contributed-templates)\nand\n[the list of pandoc boilerplates at the pandoc wiki](https://github.com/jgm/pandoc/wiki/Pandoc-Boilerplates).\n\n# Features\n1. **Simple** Your writing process is as simple as possible because you only need to write Markdown files and let the **strong defaults** of pandoc and LaTeX work for you. (see `./controls/` and `./settings/`)\n2. **Configurable** Your book projects are as configurable as possible because you can set your **metadata and variables** via YAML files and then reuse them if you want to. (see `./settings/`)\n3. **Modular** Your book projects are as modular as possible because of strict **separation of contents and presentation** (style).\nYour content live in separate directory (see `./core/`) where you can organise them intuitively.\nThe *pandoc template* itself lives in `./controls/`.\n4. State-of-the-art technology stack and low tech debt at the same time.\n\n# Preview\nDefault title page | Default info page | Default example page\n:-----------------:|:-----------------:|:--------------------:\n[![Default title page ](/examples/default_a/output/titlepage.png)](/examples/default_a/output/arabica.pdf) | [![Default info page](/examples/default_a/output/infopage.png)](/examples/default_a/output/arabica.pdf) | [![Default example page](/examples/default_a/output/examplepage.png)](/examples/default_a/output/arabica.pdf)\n\n# Examples\nGo to `./examples/` [to view a list of complete example book projects](/examples/).\n\n# Install\n## Preconditions\n1. Install [TeX Live](https://www.tug.org/texlive/) or any alternative [LaTeX distribution](https://www.latex-project.org/get/).\n2. Install [pandoc](https://pandoc.org/).\n\n## Clone\n1. Go to your templates directory: `cd /path/to/your/templates/`.\n2. Clone (or download) this repository\n`git clone https://github.com/qualiacode/arabica.git`\n3. **Done!**\n\n# Use\n## Optional: copy, paste, rename, delete\n1. Copy the entire *arabica boilerplate* located at your own local templates directory and paste the entire *arabica boilerplate* to your directory of your own projects directory:\n`cp /path/to/your/templates/arabica/* /path/to/your/projects/projectname/`\n2. Go to your project directory:\n`cd /path/to/your/projects/projectname/`\n3. Delete all the files you do not need e.g. `./examples`:\n`rm -vrf examples/*`\n\n## Set metadata\n1. Go to `./settings/00_01_metadata.yaml`\n2. Set your (meta)data, the more the better.\n3. It is a good idea to add at least one **author**, a **title** and a **year**.\n4. Enclose your values ((meta)data) in single quotes: `'()(meta)data)'`.\n5. If you want to leave a value undefined enter a tilde.\n6. Example:\n\n```yaml\ntitle: \u0026title 'Short title'\n\nsubtitle: \u0026subtitle ~\n\nauthor: \u0026author\n  - 'Jane Roe'\n  - 'John Doe'\n\nyear: '2018'\n```\n\n## Set variables\n1. You can leave the defaults and you will be fine most of the time.\n2. If you want to change things, then the same rules as in [Metadata settings](#metadata-settings) apply.\n3. Go to `./settings/00_01_settings.yaml`.\n4. Set your settings.\n5. Example:\n\n```yaml\nclassoption:\n  - 'twoside'\n  - 'twocolumn'\n  - 'parskip=full'\n\ncustom_title_page: false\n\n...\n\ntoc: true\n```\n\n## Collect\n1. Do your research, collect your bibliographic data.\n2. Go to `./bib/`\n3. Save your bibliographic data in `Bib(La)TeX` format (`.bib`) in the file `./bib/.references.bib`.\n4. Go to `./settings/00_01_settings.yaml`.\n5. Refer to your `.bib` file by adding the corresponding path of your `.bib` file as `value` to the corresponding `key`.\n6. Example (default):\n```\nbibliography: './bib/references.bib'\n```\n7. Example entry in your `.bib` file:\n```\n@article{Cantor1984,\n  langid = {german},\n  title = {Ein Beitrag zur Mannigfaltigkeitslehre},\n  volume = {1877},\n  doi = {10.1007/978-3-7091-9516-1_3},\n  journaltitle = {Über unendliche, lineare Punktmannigfaltigkeiten},\n  date = {1984},\n  pages = {25-44},\n  author = {Cantor, Georg}\n}\n```\n8. In this example your `cite key` for this bibliographic entry is `Cantor1984`.\n\n## Select\n1. Go to [CSL](http://citationstyles.org/)\n2. Dowload your desired *citation style language file* e.g. `chicago-author-date-de.csl`.\n3. Save your `.csl` fiile to: `./csl/`\n4. Go to `./settings/00_01_settings.yaml`.\n5. Refer to your `.csl` file by adding the corresponding path of your `.csl` file as `value` to the corresponding `key`.\n6. Example (default):\n```\ncsl: './csl/chicago-author-date-de.csl'\n```\n\n## Write\n1. Go to `./core/` and write you markdown files.\n2. Organise them as you like but keep in mind that pandoc will append them sequentially, determined by the alpha-numeric ordering of your file names.\n3. A good example:\n\n```\n01_introduction.md\n02_mainpart.md\n03_conclusion.md\n```\n\n## Cite\n1. Cite your sources by adding your refercences via `[@citekey]` to your markdown file(s) where ever you need them.\n2. Example:\n```\n„Cantor once said: ‚Wenn zwei wohldefinirte Mannigfaltigkeiten ...‘ [@Cantor1984]“\n```\n\n## Run\n1. Execute pandoc with the following options:\n\n```shell\npandoc                                                                      \\\n  -s                                                                        \\\n  -o ./output/projectname.pdf                                               \\\n  --data-dir=$HOME/path/to/your/projects/projectname/                       \\\n  --filter pandoc-crossref                                                  \\\n  --filter pandoc-citeproc                                                  \\\n  --pdf-engine=xelatex                                                      \\\n  --top-level-division=chapter                                              \\\n  --number-sections                                                         \\\n  --template $HOME/path/to/your/projects/projectname/controls/arabica.latex \\\n  ./core/*.md                                                               \\\n  ./settings/*.yaml                                                         \\\n  ./metadata/*.yaml\n```\n\n2. **Done!**\n\n3. Alternatively you can omit the long path in the `--template` option by copying the `arabica.latex` template located at `./controls/arabica.latex` to the default directory of your pandoc templates located at `~/.pandoc/templates/`.\n\n4. If you have copied the `arabica.latex` template into the directory of your default pandoc templates, then you can execute pandoc like this:\n\n```shell\npandoc                                                \\\n  -s                                                  \\\n  -o ./output/projectname.pdf                         \\\n  --data-dir=$HOME/path/to/your/projects/projectname/ \\\n  --filter pandoc-crossref                            \\\n  --filter pandoc-citeproc                            \\\n  --pdf-engine=xelatex                                \\\n  --top-level-division=chapter                        \\\n  --number-sections                                   \\\n  --template arabica.latex                            \\\n  ./core/*.md                                         \\\n  ./settings/*.yaml                                   \\\n  ./metadata/*.yaml\n```\n\n5. For debugging puproses you can produce a `.tex` file by runing pandoc with\n```\n-o ./output/projectname.tex\n```\n\n5. Please note, though: the *arabica boilerplate* is designed to be used with the given directory structure respectively file structure indicated in [BODYPLAN.md](./BODYPLAN.md).\nOf particular importance are the *metadata* and *settings* files: `./metadata/00_01_metadata.yaml` `./settings/00_02_settings.yaml`.\n\n6. The boilerplate should work even if you change its inner structure but keep in mind to change all the paths and variables accordingly.\nThe `arabica.template` file may work as long as you provide some basic variables used in this template file.\n\n# Enjoy\n1. Go to `./output/` and enjoy your results.\n\n# Other\n1. To read out your current default template execute:\n`pandoc -D latex \u003e default.latex`.\n\n# License\nMIT License\n\nCopyright (c) 2018 Martin Maga\n\nGo to [./LICENSE.md](./LICENSE.md).\n\n# References and Credits\n1. Plot graphics: [Gnuplot](http://gnuplot.sourceforge.net/demo_5.0/hidden2.html)\n2. Blind text: [Jasper Van der Jeugt lorem-markdownum](https://github.com/jaspervdj/lorem-markdownum)\n3. Bug fix by [Marco Torchiano \\@ StackExchange](https://tex.stackexchange.com/questions/161431/how-to-solve-longtable-is-not-in-1-column-mode-error?utm_medium=organic\u0026utm_source=google_rich_qa\u0026utm_campaign=google_rich_qa) see [Pandoc issue 1023](https://github.com/jgm/pandoc/issues/1023).\n4. [Atom editor](https://atom.io/)\n5. [Better Bib(La)TeX for Zotero](https://retorque.re/zotero-better-bibtex/)\n6. [CSL](http://citationstyles.org/)\n7. [git](https://git-scm.com/)\n8. [KOMA-Script](https://ctan.org/pkg/koma-script?lang=en)\n9. [LaTeX](https://www.latex-project.org/)\n10. [Markdown](https://daringfireball.net/projects/markdown/)\n11. [Pandoc](http://pandoc.org/)\n12. [Pandoc-citeproc](https://github.com/jgm/pandoc-citeproc)\n13. [Pandoc-crossref](https://github.com/lierdakil/pandoc-crossref)\n14. [TeXLive](https://www.tug.org/texlive/)\n15. [XeTeX](http://xetex.sourceforge.net/)\n16. [YAML](http://yaml.org/)\n17. [Zotero](https://www.zotero.org/)\n18. [zotero-citations](https://github.com/retorquere/zotero-citations)\n19. [zotero-picker](https://github.com/oztalha/zotero-picker/)\n20. [zotfile](https://github.com/jlegewie/zotfile).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperiodicpoint%2Farabica","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperiodicpoint%2Farabica","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperiodicpoint%2Farabica/lists"}