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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions