feat: initial implementation of githost extension for Quarto

README.md

@@ -1,6 +1,6 @@
-# githost Extension For Quarto
+# Githost Extension For Quarto
 
-An opinionated repository template for Quarto extension.
+A Quarto extension that automatically converts Git hosting platform references (issues, pull requests, commits, users) into clickable links. Supports **GitHub**, **GitLab**, **Codeberg**, **Gitea**, and **Bitbucket**.
 
 ## Installation
 
@@ -13,18 +13,187 @@ If you're using version control, you will want to check in this directory.
 
 ## Usage
 
-## Example
+### Basic Configuration
 
-Here is the source code for a minimal example: [example.qmd](example.qmd).
+Add the extension to your document's YAML front matter:
 
-Outputs of `example.qmd`:
+```yaml
+---
+title: "My Document"
+filters:
+  - githost
+extensions:
+  githost:
+    platform: github              # Platform: github, gitlab, codeberg, gitea, bitbucket
+    base-url: https://github.com   # Base URL (optional, auto-detected from platform)
+    repository-name: owner/repo    # Repository name for relative references
+---
+```
+
+### Supported Platforms & Reference Formats
+
+#### GitHub
+
+```yaml
+extensions:
+  githost:
+    platform: github
+    base-url: https://github.com
+    repository-name: owner/repo
+```
+
+**References:**
+
+- Issues/PRs: `#123`, `owner/repo#123`
+- Commits: `a5c3785`, `owner/repo@a5c3785`
+- Users: `@username`
+
+#### GitLab
+
+```yaml
+extensions:
+  githost:
+    platform: gitlab
+    base-url: https://gitlab.com
+    repository-name: group/project
+```
+
+**References:**
+
+- Issues: `#123`, `group/project#123`
+- Merge Requests: `!456`, `group/project!456`
+- Commits: `9ba12248`, `group/project@9ba12248`
+- Users: `@username`
+
+#### Codeberg
+
+```yaml
+extensions:
+  githost:
+    platform: codeberg
+    base-url: https://codeberg.org
+    repository-name: user/repo
+```
+
+**References:**
+
+- Issues/PRs: `#123`, `user/repo#123` (same format for both)
+- Commits: `e59ff077`, `user/repo@e59ff077`
+- Users: `@username`
+
+#### Gitea
+
+```yaml
+extensions:
+  githost:
+    platform: gitea
+    base-url: https://gitea.com
+    repository-name: user/repo
+```
+
+**References:**
+
+- Issues: `#123`, `user/repo#123`
+- Pull Requests: `!123`, `user/repo!123`
+- Commits: `e59ff077`, `user/repo@e59ff077`
+- Users: `@username`
+
+#### Bitbucket
+
+```yaml
+extensions:
+  githost:
+    platform: bitbucket
+    base-url: https://bitbucket.org
+    repository-name: workspace/repo
+```
+
+**References:**
+
+- Issues/PRs: `#123`, `workspace/repo#123` (same format for both)
+- Commits: `9cc27f2`, `workspace/repo@9cc27f2`
+- Users: `@accountname`
+
+### URL Processing
+
+The extension automatically processes full URLs and converts them to short references:
+
+**Input:** `https://github.com/owner/repo/issues/123`
+
+**Output:** `owner/repo#123` (or `#123` if it's the current repository)
+
+### Repository Detection
+
+If `repository-name` is not specified, the extension attempts to detect it from the Git remote:
+
+```bash
+git remote get-url origin
+```
+
+This works for most Git hosting platforms and extracts the `owner/repo` format from URLs like:
+
+- `https://github.com/owner/repo.git`
+- `git@gitlab.com:group/project.git`
+- `ssh://git@codeberg.org/user/repo.git`
+
+### Platform-Specific Features
+
+#### GitHub Features
+
+- Supports `GH-123` format for issues
+- Pull requests use same format as issues (`#123`)
+- Automatic 7-character SHA shortening for commits
+
+#### GitLab Features
+
+- Merge requests use `!123` format (distinct from issues)
+- Issues use `#123` format
+- URLs include `/-/` in the path structure
+- Full SHA support with automatic shortening
+
+#### Codeberg Features (Forgejo)
+
+- Issues and pull requests both use `#123` format
+- Follows Forgejo/Gitea conventions
+- Automatic reference linking in comments
+
+#### Gitea Features
+
+- Issues use `#123` format
+- Pull requests use `!123` format (GitLab-style)
+- Supports both internal and external issue trackers
+- Actionable references (closes, fixes, etc.)
+
+#### Bitbucket Features
+
+- Issues and pull requests both use `#123` format
+- Pull request URLs use `/pull-requests/` path
+- Workspace-based repository structure
+
+## Examples
+
+### Basic Usage
+
+```markdown
+See issue #123 for details.
+Commit a5c3785 fixes the bug.
+Thanks @contributor for the review!
+```
+
+### Cross-Repository References
+
+```markdown
+Related to mcanouil/quarto-github#45
+Implemented in microsoft/vscode@9ba12248
+```
+
+### Full URL Processing
+
+```markdown
+Check this issue: https://github.com/owner/repo/issues/123
+The fix is in: https://gitlab.com/group/project/-/commit/abc1234
+```
+
+## Example Document
 
-- [HTML](https://m.canouil.dev/quarto-githost/)
-- [Typst (PDF)](https://m.canouil.dev/quarto-githost/example-typst.pdf)
-- [LaTeX (PDF via `pdflatex`)](https://m.canouil.dev/quarto-githost/example-pdflatex.pdf)
-- [LaTeX (PDF via `lualatex`)](https://m.canouil.dev/quarto-githost/example-lualatex.pdf)
-- [LaTeX (PDF via `xelatex`)](https://m.canouil.dev/quarto-githost/example-xelatex.pdf)
-- [Word (DOCX)](https://m.canouil.dev/quarto-githost/example-openxml.docx)
-- [Reveal.js (HTML)](https://m.canouil.dev/quarto-githost/example-revealjs.html)
-- [Beamer (PDF)](https://m.canouil.dev/quarto-githost/example-beamer.pdf)
-- [PowerPoint (PPTX)](https://m.canouil.dev/quarto-githost/example-pptx.pptx)
+Here is the source code for a comprehensive example: [example.qmd](example.qmd)

_extensions/githost/_extension.yml

@@ -1,8 +1,7 @@
 title: Githost
 author: Mickaël Canouil
 version: 0.0.0
-quarto-required: ">=99.9.0"
+quarto-required: ">=1.8.21"
 contributes:
   filters:
     - githost.lua
-