From bd7cb61a889934297a579142e7eca2d5caea9e95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mikkel=20Roald-Arb=C3=B8l?= Date: Thu, 2 May 2024 18:38:06 +0100 Subject: [PATCH] Begin Typst template documentation --- packages/jtex/docs/_toc.yml | 1 + packages/jtex/docs/create-a-latex-template.md | 2 +- packages/jtex/docs/create-a-typst-template.md | 324 ++++++++++++++++++ packages/jtex/docs/myst.yml | 2 +- 4 files changed, 327 insertions(+), 2 deletions(-) create mode 100644 packages/jtex/docs/create-a-typst-template.md diff --git a/packages/jtex/docs/_toc.yml b/packages/jtex/docs/_toc.yml index 1c6cf6b21..cb7c1f992 100644 --- a/packages/jtex/docs/_toc.yml +++ b/packages/jtex/docs/_toc.yml @@ -4,6 +4,7 @@ parts: - caption: Guide chapters: - file: create-a-latex-template + - file: create-a-typst-template - file: create-a-beamer-template - file: contribute-a-template - caption: Reference diff --git a/packages/jtex/docs/create-a-latex-template.md b/packages/jtex/docs/create-a-latex-template.md index 95a490ad9..c1c852618 100644 --- a/packages/jtex/docs/create-a-latex-template.md +++ b/packages/jtex/docs/create-a-latex-template.md @@ -1,5 +1,5 @@ --- -title: Create a Template +title: Create a LaTeX Template description: jtex templates have a template.yml, template.tex, and any other images, class or definition files required for the template to render. thumbnail: ./thumbnails/create-a-latex-template.png --- diff --git a/packages/jtex/docs/create-a-typst-template.md b/packages/jtex/docs/create-a-typst-template.md new file mode 100644 index 000000000..053b32824 --- /dev/null +++ b/packages/jtex/docs/create-a-typst-template.md @@ -0,0 +1,324 @@ +--- +title: Create a Typst Template +description: jtex templates have a template.yml, template.typ, and any other images, class or definition files required for the template to render. +thumbnail: ./thumbnails/create-a-typst-template.png +--- + +A `jtex` template contains everything necessary to create a $\LaTeX$ document, including a `template.yml`, the main `template.typ`, and any associated files such as classes (`*.cls`), definitions (`*.def`), or images (`*.png`). +These $\LaTeX$ templates are data-driven, in that they record all of the options in a `template.yml` which you create as you are working through moving your $\LaTeX$ document to a `jtex` template. + +````{note} See the video tutorial 📺 +:class: dropdown +```{iframe} https://www.youtube.com/embed/-oD6jlM23wY +:width: 100% +``` +```` + +To get started you will need to install `jtex` and, for convenience, [cookiecutter](https://github.com/cookiecutter/cookiecutter) which allows you to get up and started in a new repository fast! + +```bash +pixi global install copier +``` + +Once installed, you can clone the [Typst template repository](https://github.com/roaldarbol/typst-template), and go through the interactive questions on the CLI prompt. + +```bash +copier gh:roaldarbol/typst-template +``` + +This process will create a template folder laid out as: + +```text +my_template +├── .github +├── README.md +├── template.yml +├── template.typ +├── [logo.png] +├── thumbnail.png +└── example + ├── main.typ + ├── ... + └── sample.bib +``` + +## Copy your template + +The first thing to do is to copy in your template into an `original` folder. +This is helpful to check in on as you transform it to a data-driven template. +If you need example data to create a default PDF, then store it in an `example` folder. + +🛠 Create an `original` folder, copy in your source files. + +To see the contents and structure of `template.yml`, see [](./template-yml.md), which defines a number of parameters and options that are available when rendering your template. The structure of the document model has standard properties, like `title`, as well as custom `template.yml` defined properties. These properties are defined in [](./document.md). + +## template.typ + +The main file in your template will be `template.typ`, which should be the full journal article or index of your book. +Take a look at the defaults in the included file, it includes `[-IMPORTS-]` and `[-CONTENT-]` as well as options that turn on/off elements of the source code, for example: + +```latex +[# if options.draft #] +Some source code +[# endif #] +``` + +🛠 Copy in the contents of your $\LaTeX$ document + +You will also need any other files necessary to render your template: + +🛠 Copy in any other style, definitions or images necessary for the template (e.g. `*.cls`, `*.bst`, `*.def`, `*.png`) + +After you have copied these, add to the `files:` entry in your `template.yml` (see [](#template-files) for details). + +🛠 Add the files necessary into `files` list in the `template.yml` + +## Template-ify your `template.typ` + +The next thing that we will do is start to change our `template.typ` into an actual template! There are a few parts of data that are available when you render the template (see [](#template-variables)). + +These objects include: + +`[-IMPORTS-]` and `[-CONTENT-]` +: The main parts of your template for imports at the top, and the main content of your document + +`doc` object +: Holds structured frontmatter information, for example `[-doc.title-]` +: See [](#document-properties) + +`options` object +: Holds custom data defined by this template, for example `[-options.my_custom_opt-]` + +`parts` object +: Holds custom "parts" of the document like an abstract, for example `[-parts.abstract-]` +: See [](#template-parts) + +### Start with the title & abstract + +Your $\LaTeX$ document probably has a title like `\title{Some title}`. Change this to: + +```latex +\title{[-doc.title-]} +``` + +The structure of the template variables is a customized Jinja environment that allows you to put variables +starting with `[-` and ending with `-]`. See [](./template-rules.md) for more information. + +Your template might also have an **abstract** in it, if so we will define this as a "part" or our document. + +```latex +[# if parts.abstract #] +\begin{abstract} +[-parts.abstract-] +\end{abstract} +[# endif #] +``` + +Here we are introducing conditional syntax for the template, that starts with `[#` and ends with `#]`. + +### Add to the `template.yml` + +The above template properties that we added also need to be added to the `template.yml`. The command line tools will tell us where we need to add information: + +```bash +jtex check +``` + +This will tell you that certain fields were found but not defined in your `template.yml`: + +```text +template.typ + [parts] The template.yml does not include part "abstract" but it is referenced in template.typ on line 18 + [doc] The template.yml does not include document property "title" but it is referenced in template.typ on line 14 + +jtex found warnings or errors in validating your template. +``` + +🛠 Update your `template.yml` with `parts` and `doc` + +For example, your template might be something like: + +```yaml +parts: + - id: abstract + required: true + description: > + A good abstract will begin with a short description of the problem being + addressed, briefly describe the new data or analyses, then briefly states + the main conclusion(s) and how they are supported and uncertainties. +doc: + - id: title + required: true +``` + +```{attention} +:class: dropdown +# Improve the Data +Often the templates that journals provide include a lot of specific information about number of characters (`max_char`) or number of words (`max_words`), you can create these fields so the will be checked when you render your template. + +Other helpful information can also be included in this template `description`, for example about data availability or how to structure your acknowledgments `part`. +``` + +Try running `jtex check` again, and some of the errors will be fixed! + +```{important} +# Make the template work without values! + +Although you can mark any option or part as `required`, it is best practice to allow the template to compile without these values. + +When authors are writing their work, they often may not have the complete information, and still want a preview of their document. Your template should work in an incomplete state! + +ultimately this means wrapping your `parts` in conditional statements, such as `[# if parts.abstract #]` or providing fallbacks. +``` + +## Update the authors and affiliations + +The authors and affiliations are usually the hardest part to template as many journals do these differently. +If you are looking for inspiration, take a look at some of the existing templates in the [myst-templates](https://github.com/myst-templates) organization on GitHub. + +For example, to create the following author/affiliations list: + +```latex +\authors{First Author\affil{1}, Author\affil{1,2}} + +\affiliation{1}{First Affiliation} +\affiliation{2}{Second Affiliation} +``` + +The `jtex` template is as follows: + +```latex +\authors{ +[#- for author in doc.authors -#] +[-- author.name --] +[#- if author.affiliations -#] +\affil{ +[-- author.affiliations|join(",", "index") --] +} +[#- endif -#] +[#- if not loop.last #], [# endif -#] +[#- endfor -#] +} + +[# for affiliation in doc.affiliations #] +\affiliation{[-affiliation.index-]}{[-affiliation.value-]} +[# endfor #] +``` + +The extra `-` in some of the template variables (e.g. `[-- author.name --]`) allows you to [control whitespace](#controlling-whitespace) so that the final template collapses onto a single like like the example. + +Most of the time you can get most of the way there with `if` statements and `for` loops (including the special `loop.last` variable). The `| join(",", "index")` is often helpful for affiliations. You can read more about specifics of templating in [](./template-rules.md). + +```{tip} +# Getting Help +If you get stuck, open a [discussion on myst-templates](https://github.com/orgs/myst-templates/discussions) and someone will help you out! +``` + +## Options + +Your template may also have specific options that are not covered by the document model, and are not a "part". Good examples of this are `keypoint`, `draft` or `journal_name`. To add these add a `[-options.journal_name-]` and follow the instructions in running `jtex check` when you save. + +```yaml +options: + - type: string + id: keypoint + description: Summarize the main point and conclusions of the article + max_chars: 140 + - type: boolean + id: draft + description: Mark the document as draft with line numbers and a watermark + - type: choice + id: journal_name + required: true + description: The journal you are submitting this manuscript to! + choices: + - Nature + - Science + - Curvenote +``` + +The options can be of `type:` `string`, `boolean` or `choice`. For all of your variable names, prefer `lowercase_underscores` for the naming convention. You can also provide a `title` for any `part` or `option`. + +## Content, Imports and Packages + +The next sections to template are the main content section, which you can replace with `[-CONTENT-]` and a place before `\begin{document}` in your `template.typ`, put in the `[-IMPORTS-]`. + +The imports will be dynamically created based on your content, including any math macros that you might use. +The imports are also not included if they are already present in your template. You can define these in the `packages` list of your `template.yml`. + +To automatically find packages, ensure that your `files` list is up to date (including any style or other classes), and `jtex` will (naively) parse these and provide warnings. To put the automatically found packages into your `template.yml`, **save** and run: + +```bash +jtex check --fix +``` + +This will overwrite your `template.yml` with all packages found and there should be very few issues found automatically by `jtex check`. + +```{figure} ./images/jtex-check-fix.png +:width: 100% + +Using `jtex check --fix` will fix as many errors as possible with your `template.yml`! +``` + +## Build with content + +Your template should now be in a place where it can be used to render content. For this we will use the `myst` command line tool. + +Create a markdown file with your content, with some frontmatter that looks like: + +```yaml +--- +title: My article title +exports: + - format: tex + template: ../my_template # The folder with your template.yml in it + draft: true # Any options + journal_name: Nature + keypoint: I know how to make a MyST Markdown template. +authors: + - name: Rowan Cockett + orcid: 0000-0002-7859-8394 + affiliations: + - Curvenote +keywords: + - MyST Templates +--- +``` + +Ensure that the exports list has a `format: tex` in it. To also have your `parts` defined, use blocks with JSON metadata: + +```markdown ++++ {"part": "abstract"} + +This is your abstract! + ++++ + +# Introduction + +Other content! +``` + +You can now render your document with: + +```bash +myst build my-document.md --tex +``` + +By default these are put in a `_build` folder. If you want to control that, use the `output:` field in the appropriate export. If you have $\LaTeX$ installed, you can also try changing the format to `pdf` or `pdf+tex` to keep the source files. See [](/guide/creating-pdf-documents) for more information on using MyST templates for $\LaTeX$. + +Check that you are happy with the output tex files, and that all of the files are listed and copied over properly. If you build a PDF, save a thumbnail of one of the pages as `thumbnail.png`. + +## Create a Repository + +The default template repository creates a GitHub Action, that checks your template for obvious errors using `jtex check`. +Push your template to a GitHub repository, and you will see the actions test any time you update your template. + +```{seealso} +# Contribute to Community Templates +You can choose to also list your template so that it is available to any one else who uses `jtex` and `myst`. + +See [](./contribute-a-template.md) for more information! +``` + +Nice work on creating a template, share the word on [twitter](https://twitter.com/intent/tweet?text=I%20just%20created%20a%20new%20MyST%20Markdown%20template!&url=https://mystmd.org/jtex/create-a-latex-template&via=executablebooks), and think about [contributing your template](./contribute-a-template.md) to make it discoverable to other users! diff --git a/packages/jtex/docs/myst.yml b/packages/jtex/docs/myst.yml index 8c3614c9d..8d87e1cd8 100644 --- a/packages/jtex/docs/myst.yml +++ b/packages/jtex/docs/myst.yml @@ -3,7 +3,7 @@ project: title: JTeX github: https://github.com/executablebooks/mystmd/tree/main/packages/jtex license: MIT - subject: Jinja LaTeX Templates + subject: Jinja Templates site: title: JTeX domains: