Skip to content

Commit 9f2064c

Browse files
nleanbanleanba
committed
added changelog to readme
1 parent ae0109d commit 9f2064c

2 files changed

Lines changed: 126 additions & 49 deletions

File tree

‎.github/README.md‎

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
# Marginalia
2-
_Configurable margin-notes with smart positioning and matching wide blocks for Typst_
2+
3+
_Configurable margin-notes with smart positioning and matching wide blocks for
4+
Typst_
35

46
> [!NOTE]
5-
> This is the readme file for the project repository and contains more development-oriented info.
6-
>
7+
> This is the readme file for the project repository and contains more
8+
> development-oriented info.
9+
>
710
> [A more friendly readme for the published package can be found on Typst Universe.](https://typst.app/universe/package/marginalia).
811
912
## Docs
@@ -14,38 +17,49 @@ _Configurable margin-notes with smart positioning and matching wide blocks for T
1417

1518
[![first page of the documentation](https://github.com/nleanba/typst-marginalia/raw/refs/heads/main/preview.svg)](https://github.com/nleanba/typst-marginalia/blob/main/Marginalia.pdf)
1619

17-
1820
## Development
1921

20-
- Remember to `typst watch main.typ Marginalia.pdf` and `typst watch main.typ preview.svg --pages 1` while development to make these stay current.
22+
- Remember to `typst watch main.typ Marginalia.pdf` and
23+
`typst watch main.typ preview.svg --pages 1` while development to make these
24+
stay current.
2125

2226
### Tests
2327

2428
Use `tt run` to check for test regressions.
2529

26-
The tests don’t necessarily represent _ideal_ behavior. If the behavior improves, they should be updated.
27-
Use `tt update <name>` to update the reference of a test, and `tt new <name>` to create a new test.
30+
The tests don’t necessarily represent _ideal_ behavior. If the behavior
31+
improves, they should be updated. Use `tt update <name>` to update the reference
32+
of a test, and `tt new <name>` to create a new test.
2833

2934
> [!IMPORTANT]
30-
> Note that the tests need to have a modified `numbering` style as the GitHub CI runner does not have Inter.
35+
> Note that the tests need to have a modified `numbering` style as the GitHub CI
36+
> runner does not have Inter.
3137
3238
### New Versions
3339

34-
1. Replace all occurrences of the old version number with the new one, except where it refers to specific changes made in that version.
35-
- Also replace placeholder `?.?.?` with the new number.
40+
1. Replace all occurrences of the old version number with the new one, except
41+
where it refers to specific changes made in that version.
42+
43+
- Also replace placeholder `?.?.?` with the new number.
44+
3645
2. Commit and create a tagged release.
3746
3. “Sync Fork” in https://github.com/nleanba/typst-packages
3847
4. In `nleanba/typst-packages`, Pull and create new branch from main
39-
5. Create folder `packages/preview/marginalia/<VERSION>` and copy `LICENSE`, `README.md`, `lib.typ`, and `typst.toml`
48+
5. Create folder `packages/preview/marginalia/<VERSION>` and copy `LICENSE`,
49+
`README.md`, `lib.typ`, and `typst.toml`
4050
6. Commit and create a pull-request to `typst/packages`.
4151
7. `main.typ`: reset `#let VERSION = "?.?.?"`.
4252

4353
### Contributing
4454

45-
This is a personal project of mine.
46-
I welcome bug reports and feature requests, but I don’t consider this a community project and have no real interest in reviewing pull-requests etc.
55+
This is a personal project of mine. I welcome bug reports and feature requests,
56+
but I don’t consider this a community project and have no real interest in
57+
reviewing pull-requests etc.
4758

4859
## Feedback
49-
Have you encountered a bug? [Please report it as an issue.](https://github.com/nleanba/typst-marginalia/issues)
5060

51-
Has this package been useful to you? [I am always happy when someone gives me a ~~sticker~~ star⭐](https://github.com/nleanba/typst-marginalia)
61+
Have you encountered a bug?
62+
[Please report it as an issue.](https://github.com/nleanba/typst-marginalia/issues)
63+
64+
Has this package been useful to you?
65+
[I am always happy when someone gives me a ~~sticker~~ star⭐](https://github.com/nleanba/typst-marginalia)

‎README.md‎

Lines changed: 97 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,12 @@ If `book` is `false`, `inner` and `outer` correspond to the left and right
2121
margins respectively. If book is true, the margins swap sides on even and odd
2222
pages. Notes are placed in the outside margin by default.
2323

24-
Where you can then customize these options to your preferences.
25-
Shown here (as comments) are the default values taken if the corresponding keys are unset.
24+
Where you can then customize these options to your preferences. Shown here (as
25+
comments) are the default values taken if the corresponding keys are unset.
2626
[Please refer to the PDF documentation for more details on the configuration and the provided commands.](https://github.com/nleanba/typst-marginalia/blob/v0.3.0/Marginalia.pdf?raw=true)
2727

28-
Additionally, I recommend using Typst's partial function application feature to customize other aspects of the notes consistently:
28+
Additionally, I recommend using Typst's partial function application feature to
29+
customize other aspects of the notes consistently:
2930

3031
```typ
3132
#let note = note.with(/* options here */)
@@ -36,24 +37,27 @@ Additionally, I recommend using Typst's partial function application feature to
3637

3738
Provided via the `#note[...]` command.
3839

39-
*New in version 0.3.0:* Notes can be labeled and referenced:
40-
If you write `#note[]<xyz>`, then `@xyz` just works!
40+
_New in version 0.3.0:_ Notes can be labeled and referenced: If you write
41+
`#note[]<xyz>`, then `@xyz` just works!
4142

42-
- `#note(side: "inner")[...]` to put it on the inside margin (left margin for single-sided documents).
43+
- `#note(side: "inner")[...]` to put it on the inside margin (left margin for
44+
single-sided documents).
4345

4446
Also accepts: `auto`=`"outer"`, `"left"`, `"right"`.
4547

4648
- `#note(counter: none)[...]` to remove the marker.
4749

48-
The display of the marker can be customized with the `numbering`, `anchor-numbering`, and `flush-numbering` parameters. Refer to the docs for details.
50+
The display of the marker can be customized with the `numbering`,
51+
`anchor-numbering`, and `flush-numbering` parameters. Refer to the docs for
52+
details.
4953

5054
- `#note(shift: false)[...]` to force exact position of the note.
5155

52-
Also accepts `auto` (behavior depends on whether it has a marker), `true`, `"avoid"` and `"ignore"`.
56+
Also accepts `auto` (behavior depends on whether it has a marker), `true`,
57+
`"avoid"` and `"ignore"`.
5358

5459
- And more options for fine control. All details are in the docs.
5560

56-
5761
## Wide Blocks
5862

5963
Provided via the `#wideblock[...]` command.
@@ -62,33 +66,40 @@ Provided via the `#wideblock[...]` command.
6266

6367
Also accepts: `auto`=`"outer"`, `"left"`, `"right"`, or `"both"`.
6468

65-
Note: Wideblocks do not handle pagebreaks well, especially in `book: true` documents. This is a limitation of Typst which does not (yet) provide a robust way of detecting and reacting to page breaks.
69+
Note: Wideblocks do not handle pagebreaks well, especially in `book: true`
70+
documents. This is a limitation of Typst which does not (yet) provide a robust
71+
way of detecting and reacting to page breaks.
6672

6773
## Figures
6874

69-
You can use figures as normal, also within wideblocks.
70-
To get captions on the side, use
75+
You can use figures as normal, also within wideblocks. To get captions on the
76+
side, use
7177

7278
1. If you want top-aligned captions:
73-
```typ
74-
#set figure(gap: 0pt) // neccessary in both cases
75-
#set figure.caption(position: top)
76-
#show figure.caption.where(position: top): note.with(
77-
alignment: "top", counter: none, shift: "avoid", keep-order: true,
78-
dy: -0.01pt, // this is so that the caption is placed above wide figures.
79-
)
80-
```
79+
80+
```typ
81+
#set figure(gap: 0pt) // neccessary in both cases
82+
#set figure.caption(position: top)
83+
#show figure.caption.where(position: top): note.with(
84+
alignment: "top", counter: none, shift: "avoid", keep-order: true,
85+
dy: -0.01pt, // this is so that the caption is placed above wide figures.
86+
)
87+
```
88+
8189
2. If you want bottom-aligned captions:
82-
```typ
83-
#set figure(gap: 0pt) // neccessary in both cases
84-
#set figure.caption(position: bottom) // (this is the default)
85-
#show figure.caption.where(position: bottom): note.with(
86-
alignment: "bottom", counter: none, shift: "avoid", keep-order: true)
87-
```
90+
91+
```typ
92+
#set figure(gap: 0pt) // neccessary in both cases
93+
#set figure.caption(position: bottom) // (this is the default)
94+
#show figure.caption.where(position: bottom): note.with(
95+
alignment: "bottom", counter: none, shift: "avoid", keep-order: true)
96+
```
8897

8998
### Figures in the Margin
9099

91-
For small figures, the package also provides a `notefigure` command which places the figure in the margin.
100+
For small figures, the package also provides a `notefigure` command which places
101+
the figure in the margin.
102+
92103
```typ
93104
#notefigure(
94105
rect(width: 100%),
@@ -98,24 +109,76 @@ For small figures, the package also provides a `notefigure` command which places
98109

99110
It takes all the same options as `#note[]`, with some additions. In particular,
100111

101-
- You can use `#notefigure(note-label: <xyz>, ..)` to label the underlying note (if you want to reference it like a note)
112+
- You can use `#notefigure(note-label: <xyz>, ..)` to label the underlying note
113+
(if you want to reference it like a note)
102114

103-
- `#notefigure(show-caption: .., ..)` is how you change the caption rendering. NB.: this function is expected to take two arguments, please consult the docs.
115+
- `#notefigure(show-caption: .., ..)` is how you change the caption rendering.
116+
NB.: this function is expected to take two arguments, please consult the docs.
104117

105118
## Utilities
106119

107120
- `#marginalia.header()` for easy two/three-column headers
108121
- `#show: marginalia.show-frame` to show the page layout with background lines
109-
- `#marginalia.note-numbering()` to generate your own numberings from sequences of symbols
110-
- `#marginalia.ref()` to reference notes by relative index, without using labels.
111-
- `#marginalia.get-left()` and `#marginalia.get-right()` to get contextual layout information.
122+
- `#marginalia.note-numbering()` to generate your own numberings from sequences
123+
of symbols
124+
- `#marginalia.ref()` to reference notes by relative index, without using
125+
labels.
126+
- `#marginalia.get-left()` and `#marginalia.get-right()` to get contextual
127+
layout information.
112128

113129
## Manual
114130

115131
[Full Manual →](https://github.com/nleanba/typst-marginalia/blob/v0.3.0/Marginalia.pdf?raw=true)
116132
[![first page of the documentation](https://github.com/nleanba/typst-marginalia/raw/refs/tags/v0.3.0/preview.svg)](https://github.com/nleanba/typst-marginalia/blob/v0.3.0/Marginalia.pdf?raw=true)
117133

134+
### Changelog
135+
136+
- 0.3.0
137+
- Notes and notefigures can now be labeled and referenced. The `label`
138+
parameter on notefigures has been removed, a `note-label` parameter has been
139+
added.
140+
- Recommended way to disable numbering a note is using `counter: none`, this
141+
now works uniformly for notes and notefigures. (Enable markers for a
142+
notefigure simply by using `counter: marginalia.notecounter`)
143+
- Note markers now link to the anchor (and vice versa). Controlled via new
144+
`link-anchor` property.
145+
- 0.2.4
146+
- Pages with `height: auto` work now.
147+
- Added `ref` utility function.
148+
- 0.2.3: The counter used for notes can now be customized.
149+
- 0.2.2
150+
- More flexible `alignment` parameter replaces `align-baseline`.
151+
(`notefigure.dy` no longer takes a relative length, use `alignemnt`
152+
instead.)
153+
- Added `show-frame` and `header` utility functions.
154+
- 0.2.1: Allow customizing the anchor independently of the in-note number using
155+
`anchor-numbering`.
156+
- 0.2.0
157+
- `block-style` can now be a function, allowing to customize the style for
158+
even and odd pages.
159+
- `reverse` and `double` parameters have been replaced by a uniform `side`
160+
parameter.
161+
- Setup is now done using the `setup` show-rule. (`configure()` and
162+
`page-setup()` have been removed)
163+
- `numbering` and `flush-numbering` parameters are now per-note. (`numbered`
164+
has been removed.)
165+
- 0.1.4: New styling parameter `block-style`.
166+
- 0.1.3
167+
- New styling parameters `par-style`, and `text-style`.
168+
- Added `shift` and `keep-order` options.
169+
- 0.1.1
170+
- Notes will now avoid each other for any amount of notes.
171+
- Added `notefigure`.
172+
- Added `clearance` configuration option.
173+
174+
(Not listing bugfixes, see the
175+
[release notes on GitHub](https://github.com/nleanba/typst-marginalia/releases)
176+
for the full details.)
177+
118178
## Feedback
119-
Have you encountered a bug? [Please report it as an issue in my GitHub repository.](https://github.com/nleanba/typst-marginalia/issues)
120179

121-
Has this package been useful to you? [I am always happy when someone gives me a ~~sticker~~ star⭐](https://github.com/nleanba/typst-marginalia)
180+
Have you encountered a bug?
181+
[Please report it as an issue in my GitHub repository.](https://github.com/nleanba/typst-marginalia/issues)
182+
183+
Has this package been useful to you?
184+
[I am always happy when someone gives me a ~~sticker~~ star⭐](https://github.com/nleanba/typst-marginalia)

0 commit comments

Comments
 (0)