Merge pull request #408 from charmbracelet/v2-exp

(v2) migrate to v2 packages

Author: aymanbagabas

README.md

@@ -21,12 +21,12 @@ the stylish defaults.
 ## Usage
 
 ```go
-import "github.com/charmbracelet/glamour"
+import "charm.land/glamour/v2"
 
 in := `# Hello World
 
 This is a simple example of Markdown rendering with Glamour!
-Check out the [other examples](https://github.com/charmbracelet/glamour/tree/master/examples) too.
+Check out the [other examples](https://github.com/charmbracelet/glamour/tree/main/examples) too.
 
 Bye!
 `
@@ -40,11 +40,9 @@ fmt.Print(out)
 ### Custom Renderer
 
 ```go
-import "github.com/charmbracelet/glamour"
+import "charm.land/glamour/v2"
 
 r, _ := glamour.NewTermRenderer(
-    // detect background color and pick either the default dark or light theme
-    glamour.WithAutoStyle(),
     // wrap output at specific width (default is 80)
     glamour.WithWordWrap(40),
 )
@@ -53,10 +51,39 @@ out, err := r.Render(in)
 fmt.Print(out)
 ```
 
+### Color Downsampling
+
+Since the renderer is designed to be "pure" and always produce the same output
+for the same input, it doesn't have access to the terminal's capabilities. This
+means that color downsampling is not performed by default. In this case, use [Lip Gloss][lipgloss]
+to perform downsampling before rendering:
+
+```go
+import (
+    "charm.land/glamour/v2"
+    "charm.land/lipgloss/v2"
+)
+
+r, _ := glamour.NewTermRenderer(
+    // wrap output at specific width (default is 80)
+    glamour.WithWordWrap(40),
+)
+
+out, err := r.Render(in)
+if err != nil {
+    // handle error
+}
+
+// downsample colors based on terminal capabilities.
+lipgloss.Print(out)
+```
+
+[lipgloss]: https://github.com/charmbracelet/lipgloss
+
 ## Styles
 
-You can find all available default styles in our [gallery](https://github.com/charmbracelet/glamour/tree/master/styles/gallery).
-Want to create your own style? [Learn how!](https://github.com/charmbracelet/glamour/tree/master/styles)
+You can find all available default styles in our [gallery](https://github.com/charmbracelet/glamour/tree/main/styles/gallery).
+Want to create your own style? [Learn how!](https://github.com/charmbracelet/glamour/tree/main/styles)
 
 There are a few options for using a custom style:
 

UPGRADE_GUIDE_V2.md

@@ -0,0 +1,279 @@
+# Glamour v2 Upgrade Guide
+
+This guide will help you migrate from Glamour v1 to v2. Most upgrades are straightforward and can be completed in minutes.
+
+## Update Import Paths
+
+**Required:** All imports must use the new `charm.land` module path with `/v2`:
+
+```diff
+-import "github.com/charmbracelet/glamour"
+-import "github.com/charmbracelet/glamour/ansi"
+-import "github.com/charmbracelet/glamour/styles"
++import "charm.land/glamour/v2"
++import "charm.land/glamour/v2/ansi"
++import "charm.land/glamour/v2/styles"
+```
+
+## Update Dependencies
+
+```bash
+go get charm.land/glamour/v2@latest
+```
+
+If you need color downsampling (most apps do):
+
+```bash
+go get charm.land/lipgloss/v2@latest
+```
+
+## Remove Auto Style Detection
+
+**Breaking:** `WithAutoStyle()` has been removed. The default style is now `"dark"`.
+
+```diff
+-r, _ := glamour.NewTermRenderer(
+-    glamour.WithAutoStyle(),
+-)
++r, _ := glamour.NewTermRenderer(
++    // "dark" is the default, or specify explicitly
++    glamour.WithStylePath("dark"),
++)
+```
+
+If you were relying on automatic style selection based on terminal background, you'll need to choose the style explicitly:
+
+```go
+// For light backgrounds
+r, _ := glamour.NewTermRenderer(glamour.WithStylePath("light"))
+
+// For dark backgrounds (default)
+r, _ := glamour.NewTermRenderer(glamour.WithStylePath("dark"))
+
+// Other built-in styles: "pink", "dracula", "tokyo-night", "ascii"
+r, _ := glamour.NewTermRenderer(glamour.WithStylePath("dracula"))
+```
+
+Want to detect the terminal background yourself? You can use Lip Gloss:
+
+```go
+import "charm.land/lipgloss/v2"
+
+// Detect if we're on a dark background
+isDark := lipgloss.HasDarkBackground()
+
+style := "dark"
+if !isDark {
+    style = "light"
+}
+
+r, _ := glamour.NewTermRenderer(glamour.WithStylePath(style))
+```
+
+## Handle Color Downsampling Explicitly
+
+**Breaking:** `WithColorProfile()` has been removed. Use Lip Gloss for color adaptation:
+
+```diff
+-import "github.com/muesli/termenv"
+-
+-r, _ := glamour.NewTermRenderer(
+-    glamour.WithColorProfile(termenv.TrueColor),
+-)
+-out, _ := r.Render(markdown)
+-fmt.Print(out)
++import "charm.land/lipgloss/v2"
++
++r, _ := glamour.NewTermRenderer(
++    glamour.WithWordWrap(80),
++)
++out, _ := r.Render(markdown)
++
++// Lip Gloss handles color downsampling based on terminal capabilities
++lipgloss.Print(out)
+```
+
+Why the change? Glamour is now pure — it always produces the same output for the same input. This makes it more predictable and testable. Lip Gloss handles the terminal-specific color adaptation when you're ready to display the output.
+
+If you don't need color adaptation (e.g., you know you're always outputting TrueColor):
+
+```go
+r, _ := glamour.NewTermRenderer(glamour.WithWordWrap(80))
+out, _ := r.Render(markdown)
+fmt.Print(out)  // Direct output, no downsampling
+```
+
+## Remove Overline Styles
+
+**Breaking:** The `Overlined` field has been removed from style configurations.
+
+If you have custom styles using `Overlined`:
+
+```diff
+ StylePrimitive: ansi.StylePrimitive{
+     Bold:      &trueBool,
+     Underline: &trueBool,
+-    Overlined: &trueBool,
+ }
+```
+
+Overline was rarely supported across terminals and not widely used. If you need similar visual separation, consider alternatives like underline, bold, inverse, or background colors.
+
+## Update Custom Style Definitions
+
+If you maintain custom `StyleConfig` definitions, update the import paths:
+
+```diff
+-import "github.com/charmbracelet/glamour/ansi"
++import "charm.land/glamour/v2/ansi"
+
+ var myStyle = &ansi.StyleConfig{
+     // Your custom style definition
+     Document: ansi.StyleBlock{
+         StylePrimitive: ansi.StylePrimitive{
+             Color: stringPtr("#E6DB74"),
+         },
+     },
+ }
+```
+
+The structure is the same; only the import path changes.
+
+## Verify Custom Writers (Advanced)
+
+If you implemented custom margin or padding writers using `ansi.MarginWriter`:
+
+1. Ensure you call `.Close()` on all writer instances
+2. The new `IndentWriter` and `PaddingWriter` types are available for custom use
+
+```go
+import "charm.land/glamour/v2/ansi"
+
+mw := ansi.NewMarginWriter(ctx, w, style)
+defer mw.Close()  // Important: always close writers now
+
+// Write your content
+io.WriteString(mw, content)
+```
+
+This improves memory management and prevents resource leaks.
+
+## Example Migration
+
+Here's a complete before/after example:
+
+### Before (v1)
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/charmbracelet/glamour"
+    "github.com/muesli/termenv"
+)
+
+func main() {
+    md := `# Hello World
+
+This is **Glamour v1**!
+`
+    
+    r, _ := glamour.NewTermRenderer(
+        glamour.WithAutoStyle(),
+        glamour.WithColorProfile(termenv.TrueColor),
+        glamour.WithWordWrap(80),
+    )
+    
+    out, _ := r.Render(md)
+    fmt.Print(out)
+}
+```
+
+### After (v2)
+
+```go
+package main
+
+import (
+    "fmt"
+    "charm.land/glamour/v2"
+    "charm.land/lipgloss/v2"
+)
+
+func main() {
+    md := `# Hello World
+
+This is **Glamour v2**!
+`
+    
+    r, _ := glamour.NewTermRenderer(
+        glamour.WithStylePath("dark"),  // or omit for default
+        glamour.WithWordWrap(80),
+    )
+    
+    out, _ := r.Render(md)
+    lipgloss.Print(out)  // Handles color downsampling
+}
+```
+
+## Testing Your Migration
+
+After making changes:
+
+1. **Run your tests** — Ensure all tests pass with the new version
+2. **Visual check** — Render sample markdown and verify output looks correct
+3. **Check wrapping** — Pay special attention to text wrapping if you have CJK or emoji content (it should be better now!)
+4. **Test hyperlinks** — If you use autolinks, verify they render correctly
+
+## Common Issues
+
+### "cannot find package"
+
+Make sure you've updated your `go.mod`:
+
+```bash
+go get charm.land/glamour/v2
+```
+
+And that all imports use the new path with `/v2`.
+
+### Colors look wrong
+
+If colors aren't displaying correctly, make sure you're using `lipgloss.Print()` instead of `fmt.Print()`:
+
+```go
+out, _ := r.Render(markdown)
+lipgloss.Print(out)  // Not fmt.Print(out)
+```
+
+### Text wrapping issues
+
+Glamour v2 has improved text wrapping, especially for CJK characters and emojis. If you're seeing wrapping issues, it's likely a regression. Please [open an issue](https://github.com/charmbracelet/glamour/issues)!
+
+## Need Help?
+
+If you run into issues during migration:
+
+- Check the [examples directory](https://github.com/charmbracelet/glamour/tree/main/examples) for working code
+- Review [What's New](WHATS_NEW.md) for detailed feature changes
+- Join us on [Discord](https://charm.sh/chat)
+- Open an issue on [GitHub](https://github.com/charmbracelet/glamour/issues)
+
+## Feedback
+
+Migrated successfully? Having trouble? We'd love to hear about it!
+
+- [Discord](https://charm.sh/chat)
+- [The Fediverse](https://mastodon.social/@charmcli)
+- [Twitter](https://twitter.com/charmcli)
+
+---
+
+Welcome to Glamour v2! 💄
+
+Part of [Charm](https://charm.sh).
+
+<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>
+
+Charm热爱开源 • Charm loves open source