gdtest-page-tags
A test package demonstrating the page tags feature.
Features
- Tagged user guide pages for discoverability
- Hierarchical tag organization
- Shadow tags for internal use
- Tag icons for visual cues
Four user-guide pages tagged with flat, hierarchical, and shadow tags. Tests that tags/index.qmd is generated with all visible tags, that page-tags.js is included for client-side pill rendering, that shadow tags (needs-review, internal) are excluded from the public tag index, and that hierarchical tags like Python/Configuration create nested headings on the tags page. Tag icons are configured for Python, Tutorial, and API.
Source files
📁 gdtest_page_tags/
📄 __init__.py
"""A test package for the page tags feature."""
__version__ = "0.1.0"
__all__ = ["Widget", "create_widget", "WidgetError"]
class WidgetError(Exception):
"""Raised when a widget operation fails."""
class Widget:
"""
A configurable widget.
Parameters
----------
name
Display name of the widget.
size
Size in pixels (default 100).
"""
def __init__(self, name: str, size: int = 100):
self.name = name
self.size = size
def render(self) -> str:
"""
Render the widget to HTML.
Returns
-------
str
An HTML string.
"""
return f"<widget>{self.name}</widget>"
def resize(self, new_size: int) -> None:
"""
Resize the widget.
Parameters
----------
new_size
New size in pixels.
Raises
------
WidgetError
If new_size is negative.
"""
if new_size < 0:
raise WidgetError("Size must be non-negative")
self.size = new_size
def create_widget(name: str, size: int = 100) -> Widget:
"""
Factory function for creating widgets.
Parameters
----------
name
Display name of the widget.
size
Size in pixels (default 100).
Returns
-------
Widget
A new widget instance.
"""
return Widget(name, size) 📁 user_guide/
📄 01-intro.qmd
---
title: Introduction
tags: [Tutorial, Getting Started]
---
Welcome to the Page Tags Demo user guide!
This guide covers the basics of widget creation.
📄 02-configuration.qmd
---
title: Configuration
tags: [Python, Python/Configuration, Tutorial]
---
Learn how to configure widgets for your project.
## Basic Setup
Create a widget with default settings:
```python
from gdtest_page_tags import create_widget
w = create_widget("my-widget")
```📄 03-advanced.qmd
---
title: Advanced Usage
tags: [Python/Advanced, API, needs-review]
---
Advanced patterns for power users.
## Custom Rendering
Override the default render method for custom output.
📄 04-errors.qmd
---
title: Error Handling
tags: [Python/Advanced, API, internal]
---
How to handle errors when working with widgets.
## WidgetError
The `WidgetError` exception is raised when an invalid operation
is attempted.
📄 05-rendering.qmd
---
title: Rendering Widgets
subtitle: A deep dive into the rendering pipeline
tags: [Python, Tutorial]
---
This page has a subtitle to test tag pill placement.
## The Render Pipeline
Widgets go through a multi-step rendering pipeline before
producing their final HTML output.
📄 06-faq.qmd
---
title: Frequently Asked Questions
---
This page has no tags at all.
## Why use widgets?
Widgets provide a reusable, configurable abstraction for
building HTML components.
📄 07-tips.qmd
---
title: Tips and Tricks
description: Handy shortcuts and lesser-known features.
tags: [Tutorial]
---
This page uses description (not subtitle) with tags.
## Keyboard Shortcuts
Use Ctrl+W to close the current widget.
📄 08-best-practices.qmd
---
title: Best Practices
subtitle: Patterns for production-quality widgets
description: A curated collection of widget best practices.
tags: [Python, Tutorial]
---
This page has both subtitle and description, plus tags.
## Naming Conventions
Use descriptive names for your widgets.
📄 README.md
# gdtest-page-tags
A test package demonstrating the page tags feature.
## Features
- Tagged user guide pages for discoverability
- Hierarchical tag organization
- Shadow tags for internal use
- Tag icons for visual cues
📄 great-docs.yml
display_name: Page Tags Demo
tags:
enabled: true
index_page: true
show_on_pages: true
hierarchical: true
icons:
Python: code
Tutorial: book-open
API: plug
shadow:
- needs-review
- internal