TableauExcerptExtension Usage Rules

Copy Markdown View Source

TableauExcerptExtension is a Tableau extension that extracts excerpts from posts for use in index pages and feeds.

Core Principle

If a post already has an excerpt field, it is unmodified. Otherwise, the extension extracts an excerpt using one of three methods (in order of precedence):

  1. Range markers - Content between <!--excerpt:start--> and <!--excerpt:end-->
  2. Split marker - Content before <!--more-->
  3. Structural extraction - First paragraph(s), sentence(s), or word(s) based on text structure

Configuration

# config/config.exs
config :tableau, TableauExcerptExtension,
  enabled: true,
  range: %{
    start: "<!--\\s*excerpt:start\\s*-->",
    end: "<!--\\s*excerpt:end\\s*-->",
    remove: false
  },
  marker: %{
    pattern: "<!--\\s*more\\s*-->",
    remove: true
  },
  fallback: %{
    strategy: :paragraph,
    count: 1,
    more: "…"
  },
  processors: [
    md: TableauExcerptExtension.Processor.Markdown
  ]

Required Configuration

  • :enabled (default false) - Enable/disable the extension

Optional Configuration

  • :range - Range marker configuration (set to false to disable)

    • :start (default "<!--\\s*excerpt:start\\s*-->") - Start marker pattern
    • :end (default "<!--\\s*excerpt:end\\s*-->") - End marker pattern
    • :remove (default false) - Remove markers from post body

  • :marker - Split marker configuration (set to false to disable)

    • :pattern (default "<!--\\s*more\\s*-->") - Regex pattern string
    • :remove (default true) - Remove marker from post body

  • :fallback - Structural extraction strategy (set to false to disable)

    • :strategy (default :paragraph) - :paragraph, :sentence, or :word
    • :count - Number of units to extract (defaults vary by strategy)
    • :more (default "…") - Suffix for truncated word excerpts

  • :processors - Format-specific processors (keyword list or map)

Decision Guide: When to Use What

Choose Your Extraction Method

Use range markers when:

  • Need precise control over excerpt content
  • Excerpt should come from middle of post
  • Want different content than opening paragraphs
  • Example: Pull a key quote or summary section

Use split marker when:

  • Natural break point in content
  • Excerpt is always the opening section
  • Compatible with other static site generators
  • Most common manual approach

Use structural extraction when:

  • Consistent automatic excerpts needed
  • No manual marker management
  • Opening content works as excerpt
  • Fallback for posts without markers

Choose Your Range Marker Pattern

Use default <!--excerpt:start--> / <!--excerpt:end--> when:

  • Standard HTML comment markers are sufficient
  • Clear, explicit marker names
  • No conflicts with existing content

Use custom patterns when:

  • Different marker convention in existing content
  • Need shorter or different marker names
  • Example: <!--begin--> / <!--end-->

Set to false when:

  • Not using range markers
  • Only using split marker or structural extraction

Choose Your Split Marker Pattern

Use default "<!--\\s*more\\s*-->" when:

  • Standard HTML comment marker is sufficient
  • Compatibility with other static site generators
  • Simple, recognizable marker

Use custom pattern when:

  • Different marker convention in existing content
  • Need multiple marker variations
  • Example: "<!--\\s*(more|excerpt|break)\\s*-->"

Set to false when:

  • No manual split markers in content
  • Only using range markers or structural extraction
  • Split marker detection not needed

Choose Your Structural Extraction Strategy

Use :paragraph (default) when:

  • Content has clear paragraph structure
  • Want complete thoughts in excerpts
  • Most common use case

Use :sentence when:

  • Paragraphs are too long
  • Want more control over excerpt length
  • Need consistent excerpt sizes

Use :word when:

  • Need precise length control
  • Character/word limits required
  • Excerpts for cards or previews with strict sizing

Set to false when:

  • All posts have manual markers (range or split)
  • No automatic extraction needed
  • Explicit excerpts only

Choose Your Count

For :paragraph strategy:

  • count: 1 (default) - Single opening paragraph
  • count: 2 - Opening and second paragraph
  • Higher counts rarely needed

For :sentence strategy:

  • count: 2 (default) - Two sentences
  • count: 1 - Single sentence (very brief)
  • count: 3-4 - Longer excerpts

For :word strategy:

  • count: 25 (default) - Brief excerpt
  • count: 50-75 - Medium excerpt
  • count: 100+ - Long excerpt

Common Configuration Patterns

Range Markers Only

config :tableau, TableauExcerptExtension,
  enabled: true,
  range: %{
    start: "<!--\\s*excerpt:start\\s*-->",
    end: "<!--\\s*excerpt:end\\s*-->",
    remove: false
  },
  marker: false,
  fallback: false

Split Marker Only

config :tableau, TableauExcerptExtension,
  enabled: true,
  range: false,
  marker: %{
    pattern: "<!--\\s*more\\s*-->",
    remove: true
  },
  fallback: false

Structural Extraction Only

config :tableau, TableauExcerptExtension,
  enabled: true,
  range: false,
  marker: false,
  fallback: %{
    strategy: :paragraph,
    count: 1
  }

Custom Split Marker with Structural Extraction

config :tableau, TableauExcerptExtension,
  enabled: true,
  marker: %{
    pattern: "<!--\\s*(more|excerpt)\\s*-->",
    remove: true
  },
  fallback: %{
    strategy: :sentence,
    count: 2
  }

Word-Based Structural Extraction

config :tableau, TableauExcerptExtension,
  enabled: true,
  range: false,
  marker: false,
  fallback: %{
    strategy: :word,
    count: 50,
    more: "…"
  }

Keep Split Marker in Body

config :tableau, TableauExcerptExtension,
  enabled: true,
  marker: %{
    pattern: "<!--\\s*more\\s*-->",
    remove: false
  },
  fallback: %{
    strategy: :paragraph,
    count: 1
  }

Format Processing

Excerpts are processed by format-specific processors. For Markdown (.md files):

  1. Structural extraction filtering - Headings and horizontal rules excluded from paragraph detection
  2. Footnotes removed - Both references [^1] and definitions [^1]: text
  3. Reference links converted - [text][ref] becomes [text](url)

Unknown formats use the Passthrough processor (no filtering or cleaning).

Rendering Excerpts

Excerpts are stored in the same format as the source and must be rendered with the appropriate converter (e.g., Tableau.markdown/1 for Markdown excerpts).

See the Basic Usage guide for rendering examples and the Deduplicating Rendered Elements guide for handling duplicate scripts/styles when rendering multiple excerpts.

Common Gotchas

  1. All extraction methods disabled - Setting :range, :marker, and :fallback all to false logs a warning and disables the extension.

  2. Pattern is string - The :pattern and :start/:end values are strings that get compiled to Regex, not Regex literals.

  3. Marker removal affects body - When :remove is true, the post :body field is updated to remove the marker(s).

  4. Range marker removal default - Range markers default to :remove being false (kept in body), while split marker defaults to true (removed).

  5. Count defaults vary - When using structural extraction, the default :count depends on :strategy:

    • :paragraph → 1
    • :sentence → 2
    • :word → 25

  6. Word truncation mid-sentence - When using :word strategy, the :more string is only appended if truncation happens mid-sentence (no ending punctuation).

  7. Paragraph detection - Paragraphs are split on double newlines (\n\n+). Single newlines within paragraphs are preserved.

Resources