{"id":50708144,"url":"https://github.com/posit-dev/content-switcher","last_synced_at":"2026-06-09T13:02:32.227Z","repository":{"id":335149239,"uuid":"1138569749","full_name":"posit-dev/content-switcher","owner":"posit-dev","description":"Filter based on inline-text conditioning","archived":false,"fork":false,"pushed_at":"2026-05-06T17:00:23.000Z","size":92,"stargazers_count":2,"open_issues_count":8,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T19:05:01.753Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/posit-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-20T20:59:36.000Z","updated_at":"2026-05-06T17:00:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/posit-dev/content-switcher","commit_stats":null,"previous_names":["ashleyhenry15/content-switcher","posit-dev/content-switcher"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/posit-dev/content-switcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fcontent-switcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fcontent-switcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fcontent-switcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fcontent-switcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/posit-dev","download_url":"https://codeload.github.com/posit-dev/content-switcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fcontent-switcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34107866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T13:02:31.512Z","updated_at":"2026-06-09T13:02:32.222Z","avatar_url":"https://github.com/posit-dev.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Content Switcher Extension for Quarto\n\nA Quarto extension that enables dynamic content switching in HTML documents. Perfect for documentation that needs to show different content for multiple versions, languages, or platforms.\n\n## Features\n\n- Display different content blocks based on user selection\n- Support for both block-level and inline content switching\n- Dropdown selector with customizable position and label\n- Persistent selection using localStorage\n- URL parameter support for direct linking to specific versions\n- Auto-detection of versions from content\n- Dark mode support\n- Works seamlessly with Quarto themes\n\n## Installation\n\nInstall the extension in your Quarto project:\n\n```bash\nquarto add posit-dev/content-switcher\n```\n\nOr install a specific version:\n\n```bash\nquarto add posit-dev/content-switcher@v0.1.0\n```\n\nThis will install the extension under the `_extensions` subdirectory of your project. If you're using version control, you'll want to check in this directory.\n\n## Usage\n\n### Basic Setup\n\nAdd the extension to your document's YAML frontmatter:\n\n```yaml\n---\ntitle: \"My Document\"\nformat: html\nfilters:\n  - content-switcher\nextensions:\n  content-switcher:\n    default: \"v2026.01\"\n    versions:\n      - id: \"v2026.01\"\n        label: \"2026.01.0\"\n      - id: \"v2.0\"\n        label: \"2.0\"\n      - id: \"v3.0\"\n        label: \"3.0\"\n    selector:\n      position: \"header\"\n      label: \"Version:\"\n---\n```\n\n### Block-Level Content Switching\n\nUse divs with the `content-switcher` class to create version-specific content blocks:\n\n````markdown\n::: {.content-switcher version=\"v2026.01\"}\n## Version 2026.01.0 Example {.unlisted}\n\nUse pandas to read CSV data:\n\n```python\nimport pandas as pd\ndata = pd.read_csv('data.csv')\n```\n:::\n\n::: {.content-switcher version=\"v2.0\"}\n## Version 2.0 Example {.unlisted}\n\nUse readr to read CSV data:\n\n```r\nlibrary(readr)\ndata \u003c- read_csv('data.csv')\n```\n:::\n````\n\n**Important:** Always add `{.unlisted}` to headings inside content-switcher blocks to exclude them from the table of contents. Without this, the TOC will show headings for all versions simultaneously, even though only one version is visible at a time, leading to confusing TOC behavior.\n\n**Tip:** Use level 2 headings (`##`) for content blocks that should be individually searchable (see Limitations section for details about search indexing).\n\n### Inline Content Switching\n\nSwitch content inline within paragraphs using spans:\n\n```markdown\nYou can use [pandas]{.content-switcher version=\"v2026.01\"}[readr]{.content-switcher version=\"v2.0\"}[CSV.jl]{.content-switcher version=\"v3.0\"} to read your data files.\n```\n\n### Combining with Other Classes\n\nContent switcher blocks can be combined with other Quarto classes:\n\n```markdown\n::: {.content-switcher version=\"v2026.01\" .callout-note}\nThis is a version-specific note with callout styling.\n:::\n```\n\n## Configuration Options\n\nConfigure the extension in your document's YAML frontmatter under `extensions: content-switcher:`:\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `default` | string | `\"default\"` | The version to display by default |\n| `versions` | array | `[]` | List of version configurations |\n| `selector.position` | string | `\"header\"` | Where to place the selector: `\"header\"`/`\"top\"` (after title and description), `\"after-first-heading\"` (after first content heading), or `\"before-content\"` |\n| `selector.show` | boolean | `true` | Whether to show the version selector dropdown |\n| `selector.label` | string | `\"Version:\"` | Label text for the selector |\n\n### Version Configuration\n\nEach version in the `versions` array can be configured as:\n\n```yaml\nextensions:\n  content-switcher:\n    versions:\n      - id: \"unique-id\"        # Required: unique identifier used in version attributes\n        label: \"Display Name\"  # Optional: user-friendly name shown in dropdown (defaults to id)\n```\n\nOr as a simple string:\n\n```yaml\nextensions:\n  content-switcher:\n    versions:\n      - \"v1.0\"\n      - \"v2.0\"\n```\n\n### Selector Configuration\n\nThe selector can be customized with these options:\n\n```yaml\nextensions:\n  content-switcher:\n    selector:\n      position: \"header\"      # Where to place the selector\n      label: \"Version:\"       # Label text displayed next to dropdown\n      show: true              # Whether to show the selector (default: true)\n```\n\n## Advanced Features\n\n### URL Parameters\n\nLink directly to a specific version by adding a URL parameter:\n\n```\nhttps://example.com/docs.html?version=v2026.01\n```\n\nThe URL parameter takes precedence over localStorage.\n\n### Persistent Selection\n\nUser selections are automatically saved in localStorage and persist across page visits within the same browser.\n\n### Auto-Detection\n\nIf no versions are specified in the configuration, the extension will automatically detect versions from content blocks.\n\n### Custom Events\n\nWhen content switches between versions, a custom `content-switcher:changed` event is dispatched on the window object. You can listen for this event to trigger custom behavior:\n\n```javascript\nwindow.addEventListener('content-switcher:changed', function(event) {\n  console.log('Switched to version:', event.detail.version);\n});\n```\n\n## Limitations\n\n- **Table of Contents**: Headings inside content-switcher blocks do not behave as expected in the table of contents. Quarto's TOC system cannot dynamically update to show only the currently visible version's headings. **You should always add `{.unlisted}` to headings inside content-switcher blocks** to prevent the TOC from displaying headings for all versions simultaneously, which creates a confusing user experience.\n\n- **Search Indexing**: Quarto's search feature only creates separate search entries for **level 2 headings (`##`)** and above. Level 3 headings (`###`) and below are included in their parent section's searchable text but won't appear as separate search results.\n\n  **Important**: If you want version-specific content blocks to be individually searchable, use level 2 headings (`##`) instead of level 3 or lower. If you use `{.unlisted}` on level 3+ headings, the content will still be searchable but won't appear as a separate search result entry.\n\n  Example for searchable version blocks:\n  ```markdown\n  ::: {.content-switcher version=\"v1.0\"}\n  ## Version 1.0 Features {.unlisted}\n  Content here will be searchable as a separate entry.\n  :::\n\n  ::: {.content-switcher version=\"v2.0\"}\n  ## Version 2.0 Features {.unlisted}\n  Content here will also be searchable as a separate entry.\n  :::\n  ```\n\n## Example\n\nSee the [example.qmd](example.qmd) file for a complete working example, or view the [live demo site](https://yoursite.com).\n\n## Output Formats\n\nThis extension is designed for HTML output only. When rendering to PDF, Word, or other formats, only the default version content will be included.\n\n## Development\n\nThe extension consists of three main files:\n\n- `content-switcher.lua` - Pandoc Lua filter for processing content\n- `content-switcher.js` - Client-side JavaScript for version switching\n- `content-switcher.css` - Styling for the selector and content blocks\n\n## Requirements\n\n- Quarto \u003e= 1.3.0\n\n## License\n\n[Add your license here]\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposit-dev%2Fcontent-switcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fposit-dev%2Fcontent-switcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposit-dev%2Fcontent-switcher/lists"}