docs(quickstart): add echo and document tree

README.md

@@ -124,6 +124,10 @@ go install ./cmd/hype
 
 ```
 
+### Documentation Build Prerequisites
+
+To preview or export this repository's documentation, install Go 1.25 or newer and `tree`, and make both available on `PATH`.
+
 ### Verify Installation
 
 ```bash
@@ -1305,7 +1309,24 @@ For more examples, see the [hype repo](https://www.github.com/gopherguides/hype)
 
 # Arbitrary Commands
 
-You can also use the `cmd` tag and the `exec` attribute to run arbitrary commands and include them in your documentation. Here is the command to run the `tree` command and include it in our documentation:
+You can also use the `cmd` tag and the `exec` attribute to run arbitrary commands and include their output in your documentation. A simple example prints a greeting:
+
+```html
+<cmd exec="echo Hello from Hype"></cmd>
+
+```
+
+Here is the output:
+
+```shell
+$ echo Hello from Hype
+
+Hello from Hype
+```
+
+## Advanced Example
+
+Commands run by `cmd` must be installed on the machine building the docs; this example requires `tree`.
 
 ```html
 <cmd exec="tree" src="."></cmd>
@@ -1440,9 +1461,11 @@ The following code will parse the code/code.md and sourceable/sourceable.md docu
 
 # README Source
 
-You can view the source for this entire readme in the [.hype](https://github.com/gopherguides/corp/tree/main/.hype) directory.
+You can view the source for this README in [hype.md](https://github.com/gopherguides/hype/blob/main/hype.md). Included documentation lives in the [docs](https://github.com/gopherguides/hype/tree/main/docs) directory.
+
+Here is the current structure that we are using to create this README:
 
-Here is the current structure that we are using to create this readme:
+Commands run by `cmd` must be installed on the machine building the docs; this example requires `tree`.
 
 ```shell
 $ tree ./docs

docs/installation.md

@@ -48,6 +48,10 @@ cd hype
 go install ./cmd/hype
 ```
 
+### Documentation Build Prerequisites
+
+To preview or export this repository's documentation, install Go 1.25 or newer and `tree`, and make both available on `PATH`.
+
 ### Verify Installation
 
 ```bash

docs/quickstart/hype.md

@@ -134,7 +134,19 @@ For more examples, see the [hype repo](https://www.github.com/gopherguides/hype)
 
 # Arbitrary Commands
 
-You can also use the `cmd` tag and the `exec` attribute to run arbitrary commands and include them in your documentation. Here is the command to run the `tree` command and include it in our documentation:
+You can also use the `cmd` tag and the `exec` attribute to run arbitrary commands and include their output in your documentation. A simple example prints a greeting:
+
+```html
+<cmd exec="echo Hello from Hype"></cmd>
+```
+
+Here is the output:
+
+<cmd exec="echo Hello from Hype"></cmd>
+
+## Advanced Example
+
+Commands run by `cmd` must be installed on the machine building the docs; this example requires `tree`.
 
 ```html
 <cmd exec="tree" src="."></cmd>

hype.md

@@ -159,9 +159,11 @@ You can also use a [github action](#using-github-actions-to-update-your-readme)
 
 # README Source
 
-You can view the source for this entire readme in the [.hype](https://github.com/gopherguides/corp/tree/main/.hype) directory.
+You can view the source for this README in [hype.md](https://github.com/gopherguides/hype/blob/main/hype.md). Included documentation lives in the [docs](https://github.com/gopherguides/hype/tree/main/docs) directory.
 
-Here is the current structure that we are using to create this readme:
+Here is the current structure that we are using to create this README:
+
+Commands run by `cmd` must be installed on the machine building the docs; this example requires `tree`.
 
 <cmd exec="tree ./docs" src=".">
 

preview/preview_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -236,6 +237,7 @@ func TestServer_shouldWatch(t *testing.T) {
 
 func TestServer_Build(t *testing.T) {
 	r := require.New(t)
+	t.Setenv("PATH", t.TempDir())
 
 	tmpDir := t.TempDir()
 	mdFile := filepath.Join(tmpDir, "test.md")
@@ -256,6 +258,20 @@ func TestServer_Build(t *testing.T) {
 	r.Contains(srv.currentHTML, "<!DOCTYPE html>")
 }
 
+func TestServer_Build_MissingCommand(t *testing.T) {
+	r := require.New(t)
+
+	rootDir := t.TempDir()
+	r.NoError(os.WriteFile(filepath.Join(rootDir, "hype.md"), []byte("<cmd exec=\"tree\"></cmd>"), 0644))
+	t.Setenv("PATH", t.TempDir())
+
+	srv := New(DefaultConfig(), nil)
+	err := srv.build(context.Background(), rootDir)
+	r.ErrorIs(err, exec.ErrNotFound)
+	r.Contains(err.Error(), "cmd: $ tree")
+	r.Contains(err.Error(), "executable file not found in $PATH")
+}
+
 func TestServer_SetOutput(t *testing.T) {
 	r := require.New(t)