Skip to content

Style rule: prefer index directives over index roles in headings #14

@mmcky

Description

@mmcky

Proposed rule

Prefer {index} directives over {index} roles in section headings.

Problem

Using the index role inline in a heading makes the title hard to read in the source:

# {index}`Polars <single: Polars>`

Preferred style

Use a plain heading followed by one or more index directives:

# Polars

```{index} single: Polars
```

Rationale

  • The heading text stays clean and readable in the .md source
  • The index entries are still generated identically in the built output
  • Easier to maintain when multiple index entries are needed (just add more directives)

This came up during review of QuantEcon/lecture-python-programming#408.

Metadata

Metadata

Assignees

No one assigned

    Labels

    proposed-ruleA label for tagging proposed rules to be accepted into the QuantEcon style guide

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions