From 9cdb58e5bea96ea239cce52b30b0271d4e5274c2 Mon Sep 17 00:00:00 2001 From: Cory LaNou Date: Wed, 30 Sep 2026 14:58:39 -0500 Subject: [PATCH] docs(quickstart): add echo and document tree Add a simple command example and retain live directory listings. Document command installation and documentation-build prerequisites. Verify plain preview needs no external commands and missing commands produce clear errors. Closes #114 --- README.md | 29 ++++++++++++++++++++++++++--- docs/installation.md | 4 ++++ docs/quickstart/hype.md | 14 +++++++++++++- hype.md | 6 ++++-- preview/preview_test.go | 16 ++++++++++++++++ 5 files changed, 63 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 516cf6e..89ded76 100644 --- a/README.md +++ b/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 + + +``` + +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 @@ -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 diff --git a/docs/installation.md b/docs/installation.md index 2402ce5..d0d6607 100644 --- a/docs/installation.md +++ b/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 diff --git a/docs/quickstart/hype.md b/docs/quickstart/hype.md index 310e26c..b77f8e6 100644 --- a/docs/quickstart/hype.md +++ b/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 + +``` + +Here is the output: + + + +## Advanced Example + +Commands run by `cmd` must be installed on the machine building the docs; this example requires `tree`. ```html diff --git a/hype.md b/hype.md index e4efc10..61da5ae 100644 --- a/hype.md +++ b/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`. diff --git a/preview/preview_test.go b/preview/preview_test.go index a458599..1cb71ba 100644 --- a/preview/preview_test.go +++ b/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, "") } +func TestServer_Build_MissingCommand(t *testing.T) { + r := require.New(t) + + rootDir := t.TempDir() + r.NoError(os.WriteFile(filepath.Join(rootDir, "hype.md"), []byte(""), 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)