picospa.section
API for adding GitHub-style anchor links to section headings with automatic ID generation.
addId()
Method signature: addId({node: $section [, prefix = 'section']})
Adds an auto-generated ID to a heading element if it doesn't already have one.
Parameters
node(HTMLElement) - The heading element to add an ID toprefix(string, optional) - Custom prefix for the ID. Defaults topicospa.section.ID_PREFIX
Description
- Checks if the element already has an ID
- If no ID exists, generates one using the format:
${prefix}-${slug} - Slug is created from
$section.textContent.trim()usingpicospa._toSlug() - Only modifies elements that don't already have an ID
DOM Requirements
- Expects a valid DOM element (typically h1-h6)
- Element must have text content for slug generation
- Requires
picospa._toSlug()utility function
Example
const heading = document.querySelector('h2');
// Adds ID like "section-my-heading-text"
picospa.section.addId({node: heading});
// Adds ID like "custom-my-heading-text"
picospa.section.addId({node: heading, prefix: 'custom'});
addIds()
Method signature: addIds([{prefix = 'section'}])
Adds auto-generated IDs to all headings on the page.
Parameters
prefix(string, optional) - Custom prefix for all IDs. Defaults topicospa.section.ID_PREFIX
Description
- Queries for all heading elements (
h1, h2, h3, h4, h5, h6) - Calls
addId()for each heading element - Only affects headings without existing IDs
DOM Requirements
- Page must be fully loaded
- Heading elements (h1-h6) must exist in the DOM
Example
picospa.section.addIds();
// Adds IDs to all headings using default prefix
picospa.section.addIds({prefix: 'docs'});
// Adds IDs using "docs" prefix
addAnchor()
Method signature: addAnchor([{nodes: $section}])
Adds a hover-activated anchor link to a heading element.
Parameters
nodes: HTMLElement- The heading element to add an anchor to
Description
- First calls
addId({node: $section})to ensure the element has an ID - Checks if anchor already exists using
HAS_SECTION_ANCHOR_FLAG_NAMEdata attribute - Creates an absolutely positioned anchor link with
href="#${id}" - Sets CSS positioning:
position: absolute,left: 0,top: 0,transform: translateX(-100%) - Adds padding and uses
ANCHOR_TEXTfor content - Sets up removal handler on
pointerleaveevent - Marks element with tracking flag to prevent duplicates
DOM Requirements
- Element must have or be able to receive an ID
- Element's position should be relative or absolute (automatically set if needed)
- Requires CSS support for absolute positioning
Example
const heading = document.querySelector('h2');
// Adds hover-activated # link to the heading
picospa.section.addAnchor({node: heading});
addAnchors()
Method signature: addAnchors()
Adds hover-activated anchor links to all headings on the page.
Parameters
None
Description
- First calls
addIds()to ensure all headings have IDs - Queries for all heading elements (
h1, h2, h3, h4, h5, h6) - Adds
pointeroverevent listener to each heading - Event listener calls
addAnchor()on hover - Anchors are created dynamically on first hover
DOM Requirements
- Page must be fully loaded
- Heading elements (h1-h6) must exist in the DOM
- CSS must support absolute positioning for proper anchor placement
Example
// All headings will show # links on hover
picospa.section.addAnchors();
Behavior Notes
- Anchors appear on
pointeroverand disappear onpointerleave - Each anchor is created fresh on hover and removed after
- Uses event delegation for efficient memory usage
- Anchor links are functional for page navigation
ID_PREFIX
Default: 'section'
The prefix used when generating IDs for headings.
HAS_SECTION_ANCHOR_FLAG_NAME
Default: 'hasPicospaSectionAnchor'
Data attribute name used to track which elements have anchors to prevent duplicates.
ANCHOR_TEXT
Default: '#'
The text content displayed in anchor links.