diff --git a/content/docs/command-reference/config.md b/content/docs/command-reference/config.md index fe779931a6..d1aa97f8f3 100644 --- a/content/docs/command-reference/config.md +++ b/content/docs/command-reference/config.md @@ -239,6 +239,12 @@ to learn more about the state file (database) that is used for optimization. updates the timestamp on that entry. This way, when the database needs a cleanup, DVC can sort entries chronologically, and remove the oldest ones. +### plots + +- `plots.html_template` - sets a + [custom HTML template](/doc/command-reference/plots#html-templates) for + `dvc plots`. Accepts a path relative to the `.dvc/` folder. + ## Example: Add an S3 remote, and set it as default > 💡 Before adding an S3 remote, be sure to diff --git a/content/docs/command-reference/plots/diff.md b/content/docs/command-reference/plots/diff.md index 13e2774817..3a313f14b6 100644 --- a/content/docs/command-reference/plots/diff.md +++ b/content/docs/command-reference/plots/diff.md @@ -11,7 +11,7 @@ usage: dvc plots diff [-h] [-q | -v] [-t ] [-x ] [-y ] [--no-header] [--title ] [--x-label ] [--y-label ] [-o ] - [--show-vega] [--open] + [--show-vega] [--open] [--html-template ] [revisions [revisions ...]] positional arguments: @@ -97,6 +97,9 @@ all the current plots, without comparisons. header. A 0-based numeric index can be used to identify each column instead of names. +- `--html-template ` - path to a + [custom HTML template](/doc/command-reference/plots#html-templates). + - `-h`, `--help` - prints the usage/help message, and exit. - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no diff --git a/content/docs/command-reference/plots/index.md b/content/docs/command-reference/plots/index.md index 6460aeafa2..625df07d45 100644 --- a/content/docs/command-reference/plots/index.md +++ b/content/docs/command-reference/plots/index.md @@ -158,6 +158,20 @@ header (first row) are equivalent to field names. - `` (optional) - field name to display as the X axis label +## HTML templates + +It's possible to supply an HTML file to `dvc plot show` and `dvc plot diff` by +using the the `--html-template` option. This allows you to customize the +container where DVC will inject plots it generates. + +> ⚠️ This is a separate feature from +> [custom Vega templates](/doc/command-reference/plots#custom-templates). + +The only requirement for this HTML file is to specify the place to inject plots +with a `{plot_divs}` marker. See an +[example](/doc/command-reference/plots#example-offline-html-template) that uses +this feature to render DVC plots without an Internet connection, below. + ## Options - `-h`, `--help` - prints the usage/help message, and exit. @@ -260,3 +274,53 @@ file:///Users/usr/src/plots/classes.csv.html > A confusion matrix [template](/doc/command-reference/plots#plot-templates) is > predefined in DVC (found in `.dvc/plots/confusion.json`). + +### Example: Offline HTML Template + +The plots generated by `dvc plots` uses Vega JavaScript libraries, and by +default these load [online resources](https://vega.github.io/vega/usage/#embed). +There may be times when you need to produce plots without Internet access, or +want to customize the plots output to put some extra content, like banners or +extra text. DVC allows to replace the HTML file that contains the final plots. + +Download the Vega libraries into the directory where you'll produce the +`dvc plots`: + +```dvc +$ wget https://cdn.jsdelivr.net/npm/vega@5.10.0 -O my_vega.js +$ wget https://cdn.jsdelivr.net/npm/vega-lite@4.8.1 -O my_vega_lite.js +$ wget https://cdn.jsdelivr.net/npm/vega-embed@6.5.1 -O my_vega_embed.js +``` + +Create the following HTML file and save it in `.dvc/plots/mypage.html`: + +```html + + + + + + + + {plot_divs} + + +``` + +Note that this is a standard HTML file with only `{plot_divs}` as a placeholder +for DVC to inject plots. `