Add guide to docs

ajalt · Nov 11, 2023 · 1ea9bd9 · 1ea9bd9
1 parent 9af1de1
commit 1ea9bd9
Show file tree

Hide file tree

Showing 3 changed files with 340 additions and 199 deletions.
diff --git a/README.md b/README.md
@@ -5,205 +5,16 @@
 Mordant is a multiplatform library for rendering styled text in the terminal. You can use it to
 add color and style to text, create tables, draw animations, and more.
 
-## Usage
+Mordant has:
 
-Create a `Terminal` instance, and import any enum entries you want from `TextColors` and
-`TextStyles`. The `println` function on your `Terminal` will detect your current terminal
-capabilities and automatically downsample ANSI codes if necessary.
+* Easy colorful ANSI output with automatic detection of terminal capabilities
+* Markdown rendering directly to the terminal
+* Widgets for laying out terminal output, including lists, tables, panels, and more
+* Support for animating any widget, like progress bars and dashboards
 
-Use 
-[`color.bg`](https://ajalt.github.io/mordant/api/mordant/com.github.ajalt.mordant.rendering/-text-style/bg.html)
-to create a background color, or 
-[`color1 on color2`](https://ajalt.github.io/mordant/api/mordant/com.github.ajalt.mordant.rendering/-text-style/on.html)
-to combine a foreground and background.
-
-```kotlin
-import com.github.ajalt.mordant.rendering.TextColors.*
-import com.github.ajalt.mordant.rendering.TextStyles.*
-
-val t = Terminal()
-t.println(brightRed("You can use any of the standard ANSI colors"))
-
-val style = (bold + black + strikethrough)
-t.println(cyan("You ${(green on white)("can ${style("nest")} styles")} arbitrarily"))
-
-t.println(rgb("#b4eeb4")("You can also use true color and other color spaces like HSL"))
-```
-
-![](docs/img/example_text_styles.png)
-
-### Terminal color support detection
-
-By default, `Terminal()` will try to detect ANSI support in the current stdout stream. If you'd
-like to override the detection, you can pass a specific value to the `Terminal` constructor.
-
-For example, to always output ANSI RGB color codes, even if stdout is currently directed to a file,
-you can do this:
-
-```kotlin
-Terminal(AnsiLevel.TRUECOLOR)
-```
-
-## Tables
-
-Use the `table` DSL to quickly create tables. Mordant handles ANSI styles and wide characters like
-CJK and emoji.
-
-```kotlin
-val t = Terminal()
-t.println(table {
-    header { row("CJK", "Emojis") }
-    body { row("모ㄹ단ㅌ", "🙊🙉🙈") }
-})
-```
-
-![](docs/img/simple_table.png)
-
-Mordant gives you lots of customization for your tables, including striped row styles, row and
-column spans, and different border styles.
-
-```kotlin
-table {
-    borderStyle = SQUARE_DOUBLE_SECTION_SEPARATOR
-    align = RIGHT
-    outerBorder = false
-    column(0) {
-        align = LEFT
-        borders = ALL
-        style = magenta
-    }
-    column(3) {
-        borders = ALL
-        style = magenta
-    }
-    header {
-        style(magenta, bold = true)
-        row("", "Projected Cost", "Actual Cost", "Difference")
-    }
-    body {
-        rowStyles(blue, brightBlue)
-        borders = TOM_BOTTOM
-        row("Food", "$400", "$200", "$200")
-        row("Data", "$100", "$150", "-$50")
-        row("Rent", "$800", "$800", "$0")
-        row("Candles", "$0", "$3,600", "-$3,600")
-        row("Utility", "$145", "$150", "-$5")
-    }
-    footer {
-        style(bold = true)
-        row {
-            cell("Subtotal")
-            cell("$-3,455") { columnSpan = 3 }
-        }
-    }
-    captionBottom("Budget courtesy @dril", TextStyle(dim = true))
-}
-```
-
-![](docs/img/complex_table.png)
-
-## Layout
-
-If you need to lay out multiple widgets or strings, you can use the `grid` builder, which has an API similar to `table`,
-but doesn't apply styling by default. There are also the `horizontalLayout` and `verticalLayout` builders if you don't
-need a full grid.
-
-## Markdown
-
-Mordant can render GitHub Flavored Markdown. Hyperlinks will even be clickable if you're on a
-terminal that supports it, like recent versions of iTerm or Windows Terminal.
-
-```kotlin
-val t = Terminal()
-t.print(Markdown(Path("README.md").readText()))
-```
-
-![](docs/img/markdown.png)
-
-## Controlling the cursor
-
-You can show and hide the cursor, move it around, and clear parts of the screen with the `cursor`
-property on `Terminal`. If your terminal doesn't support cursor movements (like when output is
-redirected to a file) these commands are no-ops.
-
-```kotlin
-val t = Terminal()
-t.cursor.move {
-    up(3)
-    startOfLine()
-    clearScreenAfterCursor()
-}
-t.cursor.hide(showOnExit = true)
-```
-
-## Animations
-
-You can animate any widget like a table with `Terminal.animation`, or any regular
-string with `Terminal.textAnimation`.
-
-```kotln
-val t = Terminal()
-val a = t.textAnimation<Int> { frame ->
-    (1..50).joinToString("") {
-        val hue = (frame + it) * 3 % 360
-        TextColors.hsv(hue, 1, 1)("━")
-    }
-}
-
-t.cursor.hide(showOnExit = true)
-repeat(120) {
-    a.update(it)
-    Thread.sleep(25)
-}
-``` 
-
-![](docs/img/animation.svg)
-
-## Progress bars
-
-You can create customizable progress bars that automatically compute speed and time remaining.
-
-```kotlin
-val t = Terminal()
-val progress = t.progressAnimation {
-    text("my-file.iso")
-    percentage()
-    progressBar()
-    completed()
-    speed("B/s")
-    timeRemaining()
-}
-```
-
-The `progressAnimation` builder is currently JVM-only. On other platforms, you can still use 
-`t.animation { progressLayout { ... } }` which will render the same widget, you'll just need to call `progress.update`
-manually.
-
-![](docs/img/example_progress.png)
-
-Call `progress.start` to animate the progress, and `progress.update` or `progress.advance` as your
-task completes.
-
-## Prompting for input
-
-You can ask the user to enter text and wait for a response with `Terminal.prompt`:
-
-```kotlin
-val t = Terminal()
-val response = t.prompt("Choose a size", choices=listOf("small", "large"))
-t.println("You chose: $response")
-```
-
-```text
-$ ./example
-Choose a size [small, large]: small
-You chose: small
-```
-
-You can customize the prompt behavior further or convert the response to other types 
-creating a subclass of the `Prompt` class. Mordant includes `StringPrompt`, `YesNoPrompt`, and
-`ConfirmationPrompt` classes for common use cases.
+## Documentation
 
+The full documentation can be found on [the website](https://ajalt.github.io/mordant/).
 
 ## Installation