Add option to disable virtual template registration for layouts

Open
#9 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
javascript
Domain
frontend, tooling

Research direction

Start at the plugin code that calls addTemplate() for base.njk, docs.njk, blog.njk, and api.njk, then trace how plugin configuration is read. Decide whether the option is global or per-layout, and verify that disabled layouts no longer register while enabled layouts still do.

Written by the indexing model from the issue text.

Description

Problem

The plugin always registers virtual templates for layouts (base.njk, docs.njk, blog.njk, api.njk) via addTemplate(). When a site has its own custom layouts in _includes/layouts/, the virtual templates take precedence and cannot be overridden.

Per Eleventy's virtual templates design, when a virtual template collides with a physical file, the virtual template wins silently for includes/layouts.

Impact

Sites that want to use the plugin's useful features (filters, collections, shortcodes, markdown config, bundled plugins) but have their own custom layouts cannot override the plugin's layouts.

The dart_node site has a superior base.njk with:

  • Google Analytics
  • Mermaid diagram support
  • SVG icons instead of text characters
  • Additional JSON-LD schemas (SoftwareSourceCode)
  • Different CSS class names (.header vs .site-header)
  • Site-specific JS loaded differently

Suggestion

Add a config option to skip layout registration:

techdocPlugin({
  features: {
    layouts: false,  // Don't register virtual layout templates
  }
})

Or more granularly:

techdocPlugin({
  layouts: {
    base: false,   // Don't register base.njk
    docs: false,   // Don't register docs.njk  
    blog: true,    // Still register blog.njk
    api: true,     // Still register api.njk
  }
})

This would allow sites to use the plugin for its non-layout features while maintaining their own custom layouts.

Dominant language
JavaScript
Stars
0
Forks
0
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Nimblesite/eleventy-plugin-techdoc

All issues in Nimblesite/eleventy-plugin-techdoc

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.