Skip to content

Commit 861a526

Browse files
jdutantjdutant
authored
First line indent (#169)
1 parent 8ebbe09 commit 861a526

File tree

7 files changed

+1217
-0
lines changed

7 files changed

+1217
-0
lines changed

‎first-line-indent/LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2021 Julien Dutant
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎first-line-indent/Makefile

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
DIFF ?= diff --strip-trailing-cr -u
2+
3+
.PHONY: test
4+
5+
test: test_latex test_html
6+
7+
test_html: sample.md expected.html first-line-indent.lua
8+
@pandoc -s --lua-filter first-line-indent.lua --to=html $< \
9+
| $(DIFF) expected.html -
10+
11+
test_latex: sample.md expected.tex first-line-indent.lua
12+
@pandoc -s --lua-filter first-line-indent.lua --to=latex $< \
13+
| $(DIFF) expected.tex -
14+
15+
expected.html: sample.md first-line-indent.lua
16+
pandoc -s --lua-filter first-line-indent.lua --output $@ $<
17+
18+
expected.tex: sample.md first-line-indent.lua
19+
pandoc -s --lua-filter first-line-indent.lua --output $@ $<

‎first-line-indent/README.md

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
---
2+
title: "First Line Indent - First-line idented paragraphs
3+
in Pandoc's markdown"
4+
author: "Julien Dutant"
5+
---
6+
7+
First Line Indent
8+
=======
9+
10+
First-line idented paragraphs in Pandoc's markdown.
11+
12+
This Lua filter for Pandoc improves Pandoc's first-line ident
13+
paragraph separation style by removing first-line idents after
14+
blockquotes, lists and code blocks unless specified otherwise.
15+
16+
v1.0. Copyright: © 2021 Julien Dutant <[email protected]>
17+
License: MIT - see LICENSE file for details.
18+
19+
Introduction
20+
------------
21+
22+
In typography paragraphs can be distinguished in two ways: by vertical
23+
whitespace (a style common on the web) or by indenting their first
24+
line (a style common in books). For the latter conventions vary across
25+
typographic traditions: some (*e.g.* French) indent the first line of
26+
every paragraph while others (*e.g.* English) don't indent paragraphs
27+
after section headings and most indented material such as blockquotes
28+
or lists.
29+
30+
In Pandoc the default output uses the vertical whitespace style but
31+
can be switched in some formats (PDF via `LaTeX`, though not in `docx`
32+
or `html`) to the first-line indent style by setting the metadata
33+
variable `indent` to `true` and the `lang` variable is used to decide
34+
which convention to follow (the default is the English one).
35+
36+
However the default first-line indent style output still adds first-line indents to every paragraph that starts after a blockquote, list, code
37+
block, etc. These are typically (though not always) unwanted, namely when
38+
the text after the blockquote or list is a continuation of the same
39+
paragraph.
40+
41+
This filter improves the handling of first-line indent following
42+
indented material such as blockquotes and provides first-line indent
43+
style for html outputs:
44+
45+
1) The filter activates Pandoc's first-line indent style by setting
46+
the metadata variable `indent` to true, unless otherwise specified.
47+
2) The filter generates HTML outputs with first-line indent style. That
48+
is done by inserting CSS code in the document's metadata
49+
`header-includes` field. (Note that this still works if the document
50+
has its own `header-includes` material, but not if a
51+
`header-includes` value is given to Pandoc via the command line.)
52+
This default behaviour can be deactivated if the user wants to handle
53+
first-line indent formatting with a custom pandoc template.
54+
3) If the user manually specifies `\indent` (resp., `\noindent`) at the start
55+
of a paragraph (in markdown source), the paragraphs are typeset with
56+
(resp., without) first-line indentation in HTML output as well as
57+
LaTeX output.
58+
4) The filter removes (typically unwanted) first-line indents after
59+
blockquotes, lists, code blocks and the like. The user can
60+
override this by inserting `\indent` at the beginning of a paragraph
61+
that does require a first-line indent. By default first-line indent
62+
is removed after the block of the following types, though this can
63+
be customized by the user: block quotes, lists (of all types:
64+
unordered, ordered, numbered examples, definition lists),
65+
horizontal rules.
66+
5) A custom size for the first-line indentation in HTML and LaTeX output
67+
can be specified.
68+
69+
Usage
70+
-----
71+
72+
### Basic usage
73+
74+
Copy `first-line-indent.lua` in your document folder or in your pandoc
75+
data directory (details in [Pandoc's manual](https://pandoc.org/MANUAL.html#option--lua-filter)). Run it on your document with a
76+
command line option:
77+
78+
```bash
79+
pandoc --luafilter first-line-indent.lua SOURCE.md -o OUTPUT.html
80+
81+
pandoc -L first-line-indent.lua SOURCE.md -o OUTPUT.pdf
82+
```
83+
84+
or specify it in a defaults file (details in [Pandoc's manual](https://pandoc.org/MANUAL.html#option--defaults)).
85+
86+
This will generate HTML and PDF outputs in first-line indent paragraph
87+
separation style with the indent automatically removed after headings,
88+
blockquotes, lists of all kinds and horizontal rules.
89+
90+
If you want to keep the first-line indent of a certain paragraph after
91+
a list or blockquote, this must be done in markdown (convert your
92+
source to markdown first with pandoc). You simply add `\indent` at the
93+
beginning of the paragraph:
94+
95+
```markdown
96+
> This is a blockquote
97+
98+
\indent This paragraph will have an indent even though it follows a
99+
blockquote.
100+
```
101+
102+
### Advanced usage
103+
104+
The filter has options that can be specified in a [pandoc default
105+
file](https://pandoc.org/MANUAL.html#option--defaults) or, if the
106+
source is markdown, in the source document's metadata block.
107+
Either way they are specified as sub-fields of a `first-line-indent`
108+
field. In the source's metadata block, they are specified as
109+
follows (these are the default values):
110+
111+
```yaml
112+
first-line-indent:
113+
size: 1em
114+
auto-remove: true
115+
set-metadata-variable: true
116+
set-header-includes: true
117+
remove-after:
118+
- BlockQuote
119+
- BulletList
120+
- CodeBlock
121+
- DefinitionList
122+
- HorizontalRule
123+
- OrderedList
124+
dont-remove-after: Table
125+
```
126+
127+
And as follows in a default file:
128+
129+
```yaml
130+
metadata:
131+
first-line-indent:
132+
size: 1em
133+
auto-remove: true
134+
set-metadata-variable: true
135+
set-header-includes: true
136+
remove-after:
137+
- BlockQuote
138+
- BulletList
139+
- CodeBlock
140+
- DefinitionList
141+
- HorizontalRule
142+
- OrderedList
143+
dont-remove-after: Table
144+
```
145+
146+
The options are described below.
147+
148+
* `size`: string specificing size of the first-line indent. Must be in a
149+
format suitable for all desired outputs. `1.5em`, `2ex`, `.5pc`, `10pt`,
150+
`25mm`, `2.5cm`, `0.3in`, all work in LaTeX and HTML. `25px` only works
151+
in HTML. LaTeX commands (`\textheight`) are not supported.
152+
* `auto-remove`: whether the filter automatically removes first-line
153+
indent from paragraphs that follow blockquotes and the like, unless
154+
they start with the `\indent` string. (Default: true)
155+
* `set-metadata-variable`: whether the filter should tell Pandoc to use
156+
first-line-indent paragraph separation style by setting the metadata
157+
variable `indent` to `true`. (Default: true)
158+
* `set-header-includes`: whether the filter should add formatting code
159+
to the document's `header-includes` metadata field. Set it to false if
160+
you use a custom template instead.
161+
* `remove-after`, `dont-remove-after`: use these options to customize
162+
the automatic removal of first-line indent on paragraphs following
163+
blocks of a certain type. These options can be a single string or
164+
an list of strings. The strings are case-sensitive and should be
165+
those corresponding to [block types in Lua
166+
filters](https://pandoc.org/lua-filters.html#type-block): BlockQuote,
167+
BulletList, CodeBlock, DefinitionList, Div, Header, HorizontalRule,
168+
LineBlock, Null, OrderedList, Para, Plain, RawBlock, Table.
169+
170+
To illustrate the last option, suppose you don't want to filter to remove
171+
first-line indent after definition lists. You can add the following
172+
lines in the document's metadata block (if the source is markdown):
173+
174+
```yaml
175+
first-line-indent:
176+
dont-remove-after: DefinitionList
177+
```
178+
179+
### Styling the outputs
180+
181+
In LaTeX output the filters adds `\noindent` commands at beginning of
182+
paragraphs that shouldn't be indented. These can be controlled in
183+
LaTeX as usual.
184+
185+
In HTML output paragraphs that are explicitly marked to have no first-line
186+
indent are preceded by an empty `div` with class `no-first-line-indent-after`
187+
and those that are explictly marked (with `\indent` in the markdown
188+
source) to have a first-line indent are preceded by an empty `div` with class
189+
`first-line-indent-after`, as follows:
190+
191+
```html
192+
<ul>
193+
<li>A bullet</li>
194+
<li>list</li>
195+
</ul>
196+
<div class="no-first-line-indent-after"></div>
197+
<p>This paragraph should not have first-line indent.</p>
198+
...
199+
<div class="first-line-indent-after"></div>
200+
<p>This paragraph should have first-line indent.</p>
201+
```
202+
203+
These can be styled in CSS as follows:
204+
205+
```css
206+
p {
207+
text-indent: 1em;
208+
margin: 0;
209+
}
210+
:is(h1, h2, h3, h4, h5, h6) + p {
211+
text-indent: 0em;
212+
}
213+
:is(div.no-first-line-indent-after) + p {
214+
text-indent: 0em;
215+
}
216+
:is(div.first-line-indent-after) + p {
217+
text-indent: 1em;
218+
}
219+
```
220+
221+
The `p` rule adds a first-line identation to every paragraph (and `margin: 0` removes the default vertical space between paragraphs). The
222+
`is(h1, h2, h3, h4, h5, h6) + p` rule removes first-line indentation from
223+
every paragraph that follows a heading. The
224+
`:is(div.no-first-line-indent-after) + p` and
225+
`:is(div.first-line-indent-after) + p` rules remove/add first-line indentation
226+
from every paragraph that follows `div`s of the classes `no-first-line-indent-after` and `first-line-indent-after`, respectively.
227+
228+
Contributing
229+
------------
230+
231+
PRs welcome.
232+

0 commit comments

Comments
 (0)