Tips and tricks manual section (dandavison#1339)

* Add Tips & tricks section to manual * Clean up manual * Reorganize Tips & tricks
dvchoudh · Mar 9, 2023 · ffec84e · ffec84e
1 parent cf683c8
commit ffec84e
Show file tree

Hide file tree

Showing 11 changed files with 26 additions and 31 deletions.
diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md
@@ -19,16 +19,17 @@
   - [Navigation keybindings for large diffs](./navigation-keybindings-for-large-diffs.md)
   - [Merge conflicts](./merge-conflicts.md)
   - [Git blame](./git-blame.md)
-  - [24 bit color (truecolor)](./24-bit-color-truecolor.md)
-  - [Using Delta with tmux](./using-delta-with-tmux.md)
-  - [Using Delta with GNU Screen](./using-delta-with-gnu-screen.md)
-  - [Using Delta on Windows](./using-delta-on-windows.md)
-  - [Mouse scrolling](./mouse-scrolling.md)
-  - [Using Delta with Magit](./using-delta-with-magit.md)
   - [Supported languages and themes](./supported-languages-and-themes.md)
+- [Tips & tricks](./tips-and-tricks.md)
+  - [24 bit color (truecolor)](./tips-and-tricks/24-bit-color-truecolor.md)
+  - [Using Delta with tmux](./tips-and-tricks/using-delta-with-tmux.md)
+  - [Using Delta with GNU Screen](./tips-and-tricks/using-delta-with-gnu-screen.md)
+  - [Using Delta on Windows](./tips-and-tricks/using-delta-on-windows.md)
+  - [Mouse scrolling](./tips-and-tricks/mouse-scrolling.md)
+  - [Using Delta with Magit](./tips-and-tricks/using-delta-with-magit.md)
+  - [Save output with colors to HTML/PDF etc](./tips-and-tricks/export-to-html.md)
 - [Comparisons with other tools](./comparisons-with-other-tools.md)
 - [Build delta from source](./build-delta-from-source.md)
 - [Related projects](./related-projects.md)
 - [Full --help output](./full---help-output.md)
 - [Delta configs used in screenshots](./delta-configs-used-in-screenshots.md)
-  - [Side-by-side view](./side-by-side-view-1.md)
diff --git a/manual/src/delta-configs-used-in-screenshots.md b/manual/src/delta-configs-used-in-screenshots.md
@@ -2,7 +2,7 @@
 
 ## Side-by-side view
 
-https://github.com/vuejs/vue/commit/7ec4627902020cccd7b3f4fbc63e1b0d6b9798cd
+[https://github.com/vuejs/vue/commit/7ec4627902020cccd7b3f4fbc63e1b0d6b9798cd](https://github.com/vuejs/vue/commit/7ec4627902020cccd7b3f4fbc63e1b0d6b9798cd)
 
 ```gitconfig
 [delta]

diff --git a/manual/src/side-by-side-view-1.md b/manual/src/side-by-side-view-1.md
diff --git a/manual/src/24-bit-color-truecolor.md → ...tips-and-tricks/24-bit-color-truecolor.md b/manual/src/24-bit-color-truecolor.md → ...tips-and-tricks/24-bit-color-truecolor.md
diff --git a/manual/src/tips-and-tricks/export-to-html.md b/manual/src/tips-and-tricks/export-to-html.md
@@ -0,0 +1,14 @@
+# Save output with colors to HTML/PDF etc
+
+Install [ansifilter](https://formulae.brew.sh/formula/ansifilter).
+
+```sh
+git show \
+    | delta --no-gitconfig --file-decoration-style blue --hunk-header-decoration-style blue \
+    | ansifilter --html \
+    > /tmp/diff.html
+```
+
+Now open `/tmp/diff.html` in a web browser, print to PDF, etc.
+
+Remove the `--no-gitconfig` above to use your own delta style, but not that `ansifilter` does not handle hyperlinks or decoration boxes etc.
diff --git a/manual/src/mouse-scrolling.md → ...al/src/tips-and-tricks/mouse-scrolling.md b/manual/src/mouse-scrolling.md → ...al/src/tips-and-tricks/mouse-scrolling.md
diff --git a/manual/src/tips-and-tricks/tips-and-tricks.md b/manual/src/tips-and-tricks/tips-and-tricks.md
@@ -0,0 +1 @@
+# Tips & tricks
diff --git a/manual/src/using-delta-on-windows.md → ...tips-and-tricks/using-delta-on-windows.md b/manual/src/using-delta-on-windows.md → ...tips-and-tricks/using-delta-on-windows.md
diff --git a/manual/src/using-delta-with-gnu-screen.md → ...and-tricks/using-delta-with-gnu-screen.md b/manual/src/using-delta-with-gnu-screen.md → ...and-tricks/using-delta-with-gnu-screen.md
diff --git a/manual/src/using-delta-with-magit.md → ...tips-and-tricks/using-delta-with-magit.md b/manual/src/using-delta-with-magit.md → ...tips-and-tricks/using-delta-with-magit.md
diff --git a/manual/src/using-delta-with-tmux.md → .../tips-and-tricks/using-delta-with-tmux.md b/manual/src/using-delta-with-tmux.md → .../tips-and-tricks/using-delta-with-tmux.md
@@ -1,3 +1,5 @@
+# Using Delta with tmux
+
 If you're using tmux, it's worth checking that 24 bit color is working correctly. For example, run a color test script like [this one](https://gist.githubusercontent.com/lifepillar/09a44b8cf0f9397465614e622979107f/raw/24-bit-color.sh), or one of the others listed [here](https://gist.github.com/XVilka/8346728). If you do not see smooth color gradients, see the discussion at [tmux#696](https://github.com/tmux/tmux/issues/696). The short version is you need something like this in your `~/.tmux.conf`:
 
 ```Shell