feat: add comprehensive documentation section in example site (8 pages, EN+ES)#51
Merged
Conversation
…, figure, tabs, video) Resolves #6 - admonition (note/tip/warning/danger) with Feather SVG icons, markdown content - button (primary/secondary/outline) with icon slot, external URL detection - carousel: CSS scroll-snap with minimal JS prev/next buttons - figure: HTML5 <figure> with caption, lazy loading, local+remote resources - gallery: CSS grid thumbnails with optional :target CSS-only lightbox - tabs/tab: CSS-only radio-button tabs, keyboard-accessible (arrow keys) - video: HTML5 <video> with poster, caption, responsive container Design: - wvc- CSS prefix to avoid theme conflicts - Dark-mode aware via [data-theme] + CSS variables - Single assets/css/shortcodes.css for all styles - Feather-style open-source SVG icons (MIT) - Theme-aware code block backgrounds (slate in light/dark mode) - Copy-to-clipboard button on all code blocks (highlight + plain pre) Tests: 18 Hugo integration tests added (34 total, all passing) Demo page: exampleSite/content/docs/shortcodes.md
CRITICAL fixes: - carousel: hide prev/next buttons when 0-1 slides (C1) - tabs: errorf when >5 tabs to prevent silent content loss (C2) - video: fix boolean param parsing (string 'false' was truthy) (C3) - video: auto-enforce muted when autoplay (browser requirement) - video: auto-detect MIME type from file extension - button: remove role=button on <a> (ARIA contract violation) (C4) WARNING fixes: - figure: only use target=_blank for external href links (W1) - button, figure: add noreferrer to rel for external links (W2) - CSS: add focus-visible outlines to all button variants (W9) - CSS: merge duplicate figure/video caption styles (W8) - carousel: fix usage comment (no slide shortcode exists) (I4) Tests updated to match new behavior.
… and browser detection - Add Hugo i18n system with 79 translation keys (en.toml + es.toml) - Add Spanish content for all pages: home, about, contact, schedule, 4 programs, 9 episodes, 2 posts, docs - Add language switcher dropdown with keyboard navigation and ARIA attributes - Add browser language auto-detection (sessionStorage guard, first visit only) - Fix nav links for subpath-based multilingual site (baseURL=/wavecast/) - Replace hardcoded nav with menu-driven links using .Site.Home.RelPermalink - Add hreflang alternate links for SEO - Replace em-dashes with colons in Spanish content - Fix language dropdown hover gap (top: 100% instead of calc(100% + 4px)) - Add Spanish home page featured episode player - Add i18n test coverage (backward compat, injected, templates) - All 152 tests pass (91 JS + 39 Hugo + 22 e2e)
Resolve conflicts in: - assets/js/code-copy.js: keep i18n integration for copy button labels - layouts/_shortcodes/carousel.html: keep i18n for aria-labels - layouts/_shortcodes/video.html: keep i18n for unsupported video message
Add 8-page bilingual (EN+ES) documentation section under
exampleSite/content/docs/ covering the full user journey:
- Welcome/Overview with feature list and navigation table
- Installation (theme vs module, prerequisites, version pinning)
- Getting Started (first episode, shortcode parameters)
- Configuration (global defaults, CSS custom properties, part() selectors)
- Homepage Setup (footer player, framework attributes, theme toggle)
- Utility Shortcodes (existing page, now weighted for nav ordering)
- Front Matter (audio fields, podcast RSS fields, RSS detection)
- Advanced (source adapters, events API, persistence, keyboard shortcuts)
UX improvements for documentation discoverability:
- Docs menu entry in main nav (between Home and Programs, both languages)
- Docs nav dropdown in navbar showing all 8 pages with real-time
per-language resolution (CSS hover + keyboard accessible via
focus-within and aria-expanded JS toggling)
- 'Read the Docs' CTA button on homepage (About section)
- Info card now links to docs: 'This site is built with Wavecast.
Read the documentation to add this player to your own Hugo site.'
- Prev/Next navigation at bottom of each docs page
- Edit page links on each docs page pointing to GitHub
- Docs section page listing on the docs index page
Code quality improvements:
- Extract ~250 lines of inline CSS to external base.css
(minified, fingerprinted, with SRI; theme variables kept
inline for FOUC prevention)
- Replace {DOCS_URL} string placeholder with native Hugo
{{ .url }} i18n variable interpolation
- Remove hardcoded /wavecast/ path from menu URL processing
(use Hugo's native .URL which already includes base path)
- Consolidate duplicate table styles into single main table block
- Replace inline style attributes on episode cards with CSS classes
- Fix all Spanish i18n accents (pagina, traves, posicion, etc.)
- Add rel=canonical to head
- Make docs-nav section check configurable via params.docs.sections
- Add default [[menu.main]] entry to module-level hugo.toml
All code blocks in docs use plain <pre><code> (no Chroma
highlighting) for reliable copy-paste. Zero em-dashes throughout.
Closes #4
adurrr
added
documentation
Resolve conflicts by keeping docs documentation changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #4
What's included
8-page bilingual (EN+ES) documentation section under
exampleSite/content/docs/:::part()selectorsUX improvements for documentation discoverability:
focus-withinandaria-expandedJS)Code quality improvements:
base.css(minified, fingerprinted, SRI){DOCS_URL}placeholder with native Hugo{{ .url }}i18n/wavecast/path from menu URL processingrel=canonicalto headparams.docs.sectionshugo.tomlVerification:
<pre><code>(no Chroma) for reliable copy-paste