Mkdocs Glossary Search returns one big paragraph

Question

Each glossary entry in the mkdocs glossary.md file is written as follows in the editor, with a line space between entries:

Transaction Fee { #transaction_fee }
: Amount of cryptocurrency that must be paid by anybody submitting a transaction for inclusion on a blockchain. These fees reward block producers for their work processing transactions, and typically vary depending on network congestion.

Trustless { #trustless }
: A quality of a decentralized blockchain. Requires no parties to know or trust one another because there is no intermediary, i.e., no individual or central entity has authority or control over the system. Instead, transactions are processed according to agreed upon governance through [smart contracts](#smart_contract). At Flare, the process is secured at the network level, meaning that it is inherited by all subprotocols.

Each link to a glossary entry (for example: glossary.md#blockchain) or a search on blockchain returns the entire glossary as one large paragraph: the entire glossary as one paragraph

It would seem that mkdocs is not recognizing a new paragraph for each entry. How can we write the markdown for each glossary entry and be able to target each search entry from other pages or the search bar?

We have coded the markdown as follows:

Transaction Fee { #transaction_fee }
: Amount of cryptocurrency that must be paid by anybody submitting a transaction for inclusion on a blockchain. These fees reward block producers for their work processing transactions, and typically vary depending on network congestion.

Trustless { #trustless }
: A quality of a decentralized blockchain. Requires no parties to know or trust one another because there is no intermediary, i.e., no individual or central entity has authority or control over the system. Instead, transactions are processed according to agreed upon governance through [smart contracts](#smart_contract). At Flare, the process is secured at the network level, meaning that it is inherited by all subprotocols.

Expected search and links (glossary.md#entry_term) to return the specific entry, not the whole page.

Answer 1

You need to use headings to break up the search index into smaller blocks.

McDocs' search index will index a page in two ways:

1. The entire page is converted to a single block of plain text (what you are seeing).
2. The page is broken up into smaller blocks of plain text. One block for each heading in the page.

For example, consider the following example page:

This text is not under a heading and will only be included in the whole page block of the search index.

# Heading 1

This text will be included both in the whole page block and in a block under "Heading 1"

## Heading 1.1

This text will be included both in the whole page block and in a block under "Heading 1.1" (It is not included under "Heading 1")

This text will also be included both in the whole page block and in a block under "Heading 1.1"

# Heading 2

This text will be included both in the whole page block and in a block under "Heading 2"

To get the search index to behave as you desire, you will need to use headings rather than definition lists.

# Transaction Fee { #transaction_fee }

Amount of cryptocurrency that must be paid by anybody submitting a transaction for inclusion on a blockchain. These fees reward block producers for their work processing transactions, and typically vary depending on network congestion.

# Trustless { #trustless }

A quality of a decentralized blockchain. Requires no parties to know or trust one another because there is no intermediary, i.e., no individual or central entity has authority or control over the system. Instead, transactions are processed according to agreed upon governance through [smart contracts](#smart_contract). At Flare, the process is secured at the network level, meaning that it is inherited by all subprotocols.

Note that you can still use definition lists, but the rendered HTML is not exactly what you might expect. It will still work though.

## Transaction Fee { #transaction_fee }
: Amount of cryptocurrency that must be paid by anybody submitting a transaction for inclusion on a blockchain. These fees reward block producers for their work processing transactions, and typically vary depending on network congestion.

## Trustless { #trustless }
: A quality of a decentralized blockchain. Requires no parties to know or trust one another because there is no intermediary, i.e., no individual or central entity has authority or control over the system. Instead, transactions are processed according to agreed upon governance through [smart contracts](#smart_contract). At Flare, the process is secured at the network level, meaning that it is inherited by all subprotocols.