https://github.com/pandoc-ext/abstract-section
Write an article abstract in a normal section, not the YAML metadata.
https://github.com/pandoc-ext/abstract-section
pandoc-filter quarto-extension quarto-filter
Last synced: 5 months ago
JSON representation
Write an article abstract in a normal section, not the YAML metadata.
- Host: GitHub
- URL: https://github.com/pandoc-ext/abstract-section
- Owner: pandoc-ext
- License: mit
- Created: 2022-08-25T12:42:53.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-04-27T10:28:10.000Z (about 2 years ago)
- Last Synced: 2024-08-04T22:14:59.759Z (9 months ago)
- Topics: pandoc-filter, quarto-extension, quarto-filter
- Language: Lua
- Homepage:
- Size: 30.3 KB
- Stars: 56
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
abstract-section
==================================================================
[![GitHub build status][CI badge]][CI workflow]
Filter that ensures that "Abstract" sections are handled as
expected.
[CI badge]: https://img.shields.io/github/actions/workflow/status/pandoc-ext/abstract-section/ci.yaml?branch=main&logo=github
[CI workflow]: https://github.com/pandoc-ext/abstract-section/actions/workflows/ci.yaml
Abstract in a dedicated section
------------------------------------------------------------------
This filter allows to write a document abstract as normal sections
in the main text. It moves any section titled "abstract" from the
main text into the metadata. Most output format templates expect
the abstract to be given as part of the metadata, but writing body
text is easier and more natural.
``` markdown
# Abstract
Place abstract here.
Multiple paragraphs are possible.
```
Without this filter, the abstract would need to be placed in the
document's metadata. The additional indentation and formatting
requirements in YAML headers are frequently perceived as confusing
or annoying, especially when writing longer texts.
``` yaml
---
abstract: |
Place abstract here.
Multiple paragraphs are possible.
---
```
This filter modifies the document such that the abstract section
behaves as if it was passed as metadata. It does so by looking for
a top-level header whose ID is `abstract`. Pandoc auto-creates IDs
based on header contents, so a header titled *Abstract* will
satisfy this condition.^[1]
[1]: This requires the `auto_identifier` extension. It is
enabled by default.
The abstract can be placed anywhere in the document.
The filter assumes that the abstract runs up until the next
heading or [horizontal rule], whichever comes first. Thus the
abstract can be placed at the beginning of a document whose text
doesn't start with a heading:
``` markdown
# Abstract
The abstract text includes this.
* * * *
This text is the beginning of the document.
```
[horizontal rule]: https://pandoc.org/MANUAL.html#horizontal-rules
Usage
------------------------------------------------------------------
The filter modifies the internal document representation; it can
be used with many publishing systems that are based on pandoc.
### Plain pandoc
Pass the filter to pandoc via the `--lua-filter` (or `-L`) command
line option.
pandoc --lua-filter abstract-section.lua ...
### Quarto
Users of Quarto can install this filter as an extension with
quarto install extension pandoc-ext/abstract-section
and use it by adding `abstract-section` to the `filters` entry in
their YAML header.
``` yaml
---
filters:
- abstract-section
---
```
### R Markdown
Use `pandoc_args` to invoke the filter. See the [R Markdown
Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/lua-filters.html)
for details.
``` yaml
---
output:
word_document:
pandoc_args: ['--lua-filter=abstract-section.lua']
---
```
Multiple abstracts
------------------------------------------------------------------
It is common for certain works to include two abstracts, one in
English and one in the local language of an academic institution.
E.g., theses published at many German universities must have a
German "Zusammenfassung" in addition to the English "Abstract".
The filter can be configured to support those additional
abstract-like sections as well. The identifiers of the sections
must be listed in the `section-identifiers` field below the
`abstract-section` metadata entry. E.g.:
``` yaml
---
abstract-section:
section-identifiers:
- abstract
- sammanfattning
---
```
This will place the *Abstract* in the `abstract` variable as
before, but will also collect the contents of a *Sammanfattning*
section and place it in the `sammanfattning` field, where it can
be used for further processing, e.g., with a custom template.
License
------------------------------------------------------------------
This pandoc Lua filter is published under the MIT license, see
file `LICENSE` for details.