Interactive indexing

[dbolack-ab]

Semi-Dynamic Index building for Markdown+

Build simple, rich, or hybrid indexes with internal links. Fixes #3369

Usage

Both usage cases center around the use of the index marked extension.

#IndexName:Topic/Subtopic

Multiple Indices

This system is capable of tracking multiple indices. Entries without a declared index in their formatting will be placed in the default index Index. An index marker is a block-level marker.

Simple Index

Anywhere in the document add an index marker with no label and a list of terms to be indexed. Terms will be searched for in a case and whitespace insensitive manner.

#Topic

Complex Index Entry

There are a number of variations that can be employed here. The only requirement is the line starts with a #, has no space, and contains a Topic - and Index and a Subtopic are optional.

This generates an entry for Fireball under the topic of Elemental Spells in the Appendix: Magic index.

#Appendix\: Magic:Elemental Spells/Fireball

This generates the topic of Elemental Spells in the Appendix: Magic index.

#Appendix\: Magic:Elemental Spells

This generates the topic of Elemental Spells in the default index.

#Elemental Spells

This generates an entry for Fireball under the topic of Elemental Spells in the default index.

#Elemental Spells/Fireball

Crossreferences

This system supports crossreferencing index entries. Crossreference hyperlinks link to the crossreference target rather than a page number. Crossreference targets do not need to exist in the brew prior to being referenced; missing targets will result in the references being silently dropped on index generation.

Crossreferences are implemented by appending | followed by an optional key and then the index entry to reference.

amples:

#Cross Index Name:CrossReference Topic/CrossReference Subtopic 1|Index Name:Topic 

#Cross Index Name:CrossReference Topic/CrossReference Subtopic 2|+Index Name:Topic 1/SubTopic 1

#Cross Index Name:CrossReference Topic 2|Index Name:Topic 2

#Cross Index Name:CrossReference Topic 2/CrossReference SubTopic 3||Index Name:Topic 2

#Cross Index Name:CrossReference Topic 2/CrossReference SubTopic 4||+Index Name:Topic 2/SubTopic 2

The optional keys are:

Key	Reference Type
None	See
+	See Under
|	See Also
|+	See Also Under

The reference type is prepended to the target. The code does not enforce any particular style guide.

The above example would generate:

{{index,wide
##### Cross Index Name

- CrossReference Topic
  - CrossReference Subtopic 2
    see under [Topic 1: SubTopic 1](#idx_indexname_topic1_subtopic1)
- CrossReference Topic 2
    see [Topic 2](#idx_indexname_topic2)
  - CrossReference SubTopic 3
    see also [Topic 2](#idx_indexname_topic2)
  - CrossReference SubTopic 4
    see also under [Topic 2: SubTopic 2](#idx_indexname_topic2_subtopic2)

}}

Generating the Index

The rich index snippet, when executed, combines the simple and rich index entries into a single, alphabetized index.

If you have simple and rich entries, rich entries will be folded under the simple entries as follows:

0. Simple entries are created as top-level, un-indented entries.
1. Child entries are indented under their top-level parent.
2. If a Rich entry has no parent, it will be inserted as a top-level entry.
3. If a Rich entry has a parent and that parent does not exist in the top-level entries, the parent will be added as a new top-level entry and the Rich entry will be added as a child of that top-level entry.
4. If a Rich entry has a parent and the parent exists in the top-level entries, and the Rich entry is not listed as a child of the parent, it will be added as a new child.
5. If a Rich entry has a parent and the parent exists in the top-level entries, and the Rich entry exists, the child will be updated with an additional page reference to the new Rich entry.
6. Results are poured into the brew inside a {{index,wide }} container. If muliple indices exist, they will appear in alphabetical order separated by a \page.

Known issues.

• The snippet is not smart enough to know that it is scanning markup when looking for terms. This could create bad entries.
• The Styling is meh. I mostly emulated the existing Index snippet. We could do some dot padding, etc.

Other notes

I'm not the most efficient JS coder. I'd be very unsurprised if some of this could be condensed.

Test Brew ShareID: https://homebrewery-pr-4467.herokuapp.com/share/vtI5G0Zl_fan

This is a reconstruction of #3113 from my old fork to my new one.

[calculuschild]

Unfortunately your test brew disappeared when the PR 3313 closed. Can you remake it?

---

#Appendix: Magic:Elemental Spells|Fireball

Should this be #Appendix: Magic:Elemental Spells/Fireball ?

[calculuschild]

I can't seem to get the crossreference mode to work with the alternative options.

#Topic A|Cross B - Works
#Topic A||Cross B - Nothing
#Topic A|+Cross B - Nothing
#Topic A||+Cross B - Nothing

[dbolack-ab]

Unfortunately your test brew disappeared when the PR 3313 closed. Can you remake it?

I forgot to update the heroku URL.

Should this be #Appendix: Magic:Elemental Spells/Fireball ?

yes. I missed that entry when we made some changes to the syntax.

[dbolack-ab]

#Topic A|Cross B - Works
#Topic A||Cross B - Nothing
#Topic A|+Cross B - Nothing
#Topic A||+Cross B - Nothing

Cross references are dropped on the floor if the lookup doesn't exist. I can't tell from this snippet if you had one.

Compare with this https://homebrewery-pr-4467.herokuapp.com/share/T9i5qU8UxHcK

[calculuschild]

#Topic A|Cross B - Works
#Topic A||Cross B - Nothing
#Topic A|+Cross B - Nothing
#Topic A||+Cross B - Nothing

Cross references are dropped on the floor if the lookup doesn't exist. I can't tell from this snippet if you had one.

Compare with this https://homebrewery-pr-4467.herokuapp.com/share/T9i5qU8UxHcK

Yep, it exists. You can see I mentioned the first case works fine. The other three use the same lookup but emit nothing.

I'll check out your example in the mean time.

[dbolack-ab]

#Topic A|Cross B - Works
#Topic A||Cross B - Nothing
#Topic A|+Cross B - Nothing
#Topic A||+Cross B - Nothing

Cross references are dropped on the floor if the lookup doesn't exist. I can't tell from this snippet if you had one.
Compare with this https://homebrewery-pr-4467.herokuapp.com/share/T9i5qU8UxHcK

Yep, it exists. You can see I mentioned the first case works fine. The other three use the same lookup but emit nothing.

I'll check out your example in the mean time.

Hmm. It is failing with an implicit index, but not with an explicit...

[dbolack-ab]

@calculuschild Try your failures now.

[ericscheid]

This generates the topic of Elemental Spells in the Appendix: Magic index.

#Appendix: Magic:Elemental Spells

Where would this index entry appear?

#Games: Magic: The Gathering

1. topic of Magic: The Gathering in the Games index; or
2. topic of The Gathering in the Games: Magic index

[dbolack-ab]

This generates the topic of Elemental Spells in the Appendix: Magic index.
#Appendix: Magic:Elemental Spells

Where would this index entry appear?

#Games: Magic: The Gathering

1. topic of Magic: The Gathering in the Games index; or
2. topic of The Gathering in the Games: Magic index

I see an error crept in when I updated the example text.

The quoted example should be:

#Appendix\: Magic:Elemental Spells

Assuming the one in your question follows suit, it should be

#Games:Magic\:The Gathering

This would create a top level entry in the Games appendix.