18 Add Note Indexes

Goals

Support adding index sections to notes.

Context

A common use case is to have an index section that lists all the contents of a particular area of the text. In Dendron, we already show you all children (Private) of the current note when publishing but this is not available in the editor.

Proposal

Implement the command, Dendron: Add Index, that adds autogenerated index column at the bottom of the given note.

Details

The autogenerated index block will look like the below.

<!-- Autogenerated Index Start -->
## Index
- [[proj.one]]
- ...
<!-- Autogenerated Index End -->

When run for the first time, it will generate a child of all the immediate children of the current note. After it has run, Dendron will add indexLastUpdated attribute with the timestamp of the last added note. On subsequent runs, Add Index will only add children that have been created after the indexLastUpdated timestamp.

Special Cases

the Autogenerated Index markers are deleted
- if we can't find both the Start and End marker, Dendron will regenerate it at the very bottom of the page
- when regenerating, if the note has an indexLastUpdated property, we will add all new children that have been created since that time, otherwise, we will generate all indexes
the # Index header is deleted
- same behavior as above

a manual line has been entered inside the index block

...
- [[proj.three]]
Some manual line
<!-- Autogenerated Index end-->

in this case, we would add any new links below the last found link

...
- [[proj.three]]
- [[proj.four]]
Some manual line
<!-- Autogenerated Index end-->

user modifies a link after it has been pasted
- this is fine, Dendron doesn't process any links it already inserted in a previous run

Example

Simple Case

Take the following hiearchy

- proj.md
    - proj.one.md
    - proj.two.md
    - proj.three.md

running Dendron: Add Index inside proj when blank
- adds all entries one level below to the bottom of the note under ## Index
- creates indexLastUpdated entry in the frontmatter that has the most recent created time

---
id: ...
title: Projects
indexLastUpdated: 12345 
---

<!-- Autogenerated Index Start -->
## Index
- [[proj.one]]
- [[proj.two]]
- [[proj.three]]
<!-- Autogenerated Index End -->

Run `Add Index` when entries already exist

running Dendron: Add Index inside proj when there are already entries
- dendron will check if there are new direct children since the last indexLastUpdated time and add them to the bottom of the ## Index block

Index note exists, new [[proj.four]] created at time 12346

in this example, proj.four is added at the end of the index list

---
id: ...
title: Projects
indexLastUpdated: 12346 
---
<!-- Autogenerated Index Start -->
## Index
- [[proj.one]]
- [[proj.two]]
- [[proj.three]]
- [[proj.four]]
<!-- Autogenerated Index End -->

Index note exists but is manually modified, new [[proj.four]] created at time 12346

before

---
id: ...
title: Projects
indexLastUpdated: 12346 
---
<!-- Autogenerated Index Start -->
## Index
- [[proj.one]
- [[proj.two]]
- [[proj.three]]

after

---
id: ...
title: Projects
indexLastUpdated: 12346 
---
<!-- Autogenerated Index Start -->
## Index
- [[proj.one]]
- [[proj.two]]
- [[proj.three]]
- [[proj.four]]

FAQ

How does this behave in multi-vault?

In the initial verison, we will only generate index links to children that come from the same vault as the parent note. In the future, we might introduce an option to include multi-vault results

What happens if the direct child is a stub?

By default, Dendron will ignore stubs (Private) when scanning for indexes. This behavior can be changed with addStubs (Private). If set, Dendron will create a note for any stubs encountered.