Release v0.8.1 (#208)

.changes/v0.8.1.md

@@ -0,0 +1,3 @@
+## v0.8.1 - 2024-02-12
+### Fixed
+- -rel-link-style: Don't generate trailling '/' for static assets.

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       with:
         go-version: ${{ env.GO_VERSION }}
         cache: false
-    - uses: golangci/golangci-lint-action@v3
+    - uses: golangci/golangci-lint-action@v4
       name: Install golangci-lint
       with:
         version: latest

.github/workflows/docs.yml

@@ -23,7 +23,6 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: '16'
           cache: 'yarn'
           cache-dependency-path: docs/yarn.lock
       - name: Install Node dependencies

.goreleaser.yml

@@ -38,7 +38,7 @@ aurs:
       email: [email protected]
 
 brews:
-  - tap:
+  - repository:
       owner: abhinav
       name: homebrew-tap
       token: "{{ .Env.HOMEBREW_TAP_GITHUB_TOKEN }}"

CHANGELOG.md

@@ -8,10 +8,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
+## v0.8.1 - 2024-02-12
+### Fixed
+- -rel-link-style: Don't generate trailling '/' for static assets.
+
 ## v0.8.0 - 2024-02-11
 ### Added
 - Standalone website: Include a favicon on all generated pages.
-- Standalone: Add a "Root" link to the navbar, going to the top-level page. With `-subdir`, this will be the sub-directory listing.
+- Standalone: Add a "Root" link to the navbar, going to the top-level page.
+With `-subdir`, this will be the sub-directory listing.
 - Add -pkg-version flag to include a version number on pages in the standalone website.
 - Add -pagefind flag to enable or disable client-side search. By default, it's enabled if [pagefind](https://pagefind.app) is found on `$PATH`.
 ### Changed

docs/content/en/docs/faq.md

@@ -0,0 +1,34 @@
+---
+title: Frequently asked questions
+linkTitle: FAQ
+weight: 20
+---
+
+If your question isn't answered here,
+please [start a discussion](https://github.com/abhinav/doc2go/discussions)
+or [create an issue](https://github.com/abhinav/doc2go/issues/new).
+
+## Troubleshooting
+
+This section addresses common issues and their solutions.
+
+### My web host doesn't like "/foo" URLs. They want "/foo/" URLs.
+
+By default, doc2go generates relative links in the form:
+
+```html
+<a href="../path/to/dst">...</a>
+```
+
+If your web host prefers directories to have a trailing slash,
+run doc2go with `-rel-link-style=directory`.
+
+```sh
+doc2go -rel-link-style=directory ./...
+```
+
+This will generate:
+
+```html
+<a href="../path/to/dst/">...</a>
+```

docs/content/en/docs/publish/github-pages.md

@@ -165,3 +165,52 @@ Now, the documentation for that package will be at:
 Use the import path for your module instead of the above
 if you're using a vanity import path.
 {{% /alert %}}
+
+## Adding search
+
+doc2go supports [client-side search]({{< relref "/docs/usage/search" >}})
+powered by [Pagefind](https://pagefind.app).
+
+To add search to your documentation, follow these steps:
+
+1. Install Pagefind to your repository with NPM.
+
+    ```bash
+    npm install pagefind@latest
+    ```
+
+    This will generate a package-lock.json,
+    locking the version of Pagefind in use.
+
+2. Check in the package.json and package-lock.json into your repository.
+
+    ```bash
+    git add package.json package-lock.json
+    git commit -m "Pin Pagefind version"
+    ```
+
+    In the future, you can use `npm update` to update to the latest version.
+
+3. In the GitHub Workflow, add steps to set up Node and download Pagefind
+   before the "Generate API reference" step.
+
+    ```yaml
+              - name: Set up Node
+                uses: actions/setup-node@v4
+                with:
+                  cache: 'npm'
+                  cache-dependency-path: package-lock.json
+                  # Specify a different cache-dependency-path if you didn't
+                  # run the command in the root of the repository.
+
+              - name: Install Node dependencies
+                run: npm install
+    ```
+
+4. Modify the command in the "Generate API Reference" step
+   to pass the path to the newly installed Pagefind binary.
+
+    ```yaml
+              - name: Generate API reference
+                run: doc2go -pagefind=node_modules/.bin/pagefind ./...
+    ```

docs/content/en/docs/usage/highlight.md

@@ -1,5 +1,5 @@
 ---
-title: Syntax Highlighting
+title: Syntax highlighting
 description: >-
   Customize doc2go's syntax highlighting of code blocks.
 weight: 3

integration/integration_test.go

@@ -167,8 +167,10 @@ func TestDirectoryRelativeLinks(t *testing.T) {
 
 	root := generate(t, "-rel-link-style=directory", "./...")
 	visitLocalURLs(t, root, &visitOptions{ShouldVisit: func(local localURL) bool {
-		if local.Kind != localPage {
-			return false
+		if local.Kind == localAsset {
+			return assert.False(t,
+				strings.HasSuffix(local.URL.Path, "/"),
+				"%v: path for relative asset ends with '/': %v", local.From, local.Href)
 		}
 
 		href := local.Href

internal/html/render.go

@@ -446,6 +446,13 @@ func (r *render) relativePath(p string) string {
 	return p
 }
 
+// Returns the relative path to a file, generally a static asset.
+//
+// No trailing '/' is added.
+func (r *render) relativePathFile(p string) string {
+	return relative.Path(r.Path, p)
+}
+
 // Returns the path to a static asset stored in the output directory.
 // If -subdir was used, these assets are shared with other websites.
 func (r *render) static(p string) string {
@@ -454,7 +461,7 @@ func (r *render) static(p string) string {
 		elem = append(elem, "..")
 	}
 	elem = append(elem, StaticDir, p)
-	return r.relativePath(path.Join(elem...))
+	return r.relativePathFile(path.Join(elem...))
 }
 
 // Returns the path to an asset stored in the site directory
@@ -463,7 +470,7 @@ func (r *render) static(p string) string {
 func (r *render) siteStatic(p string) string {
 	elem := []string{r.Home}
 	elem = append(elem, StaticDir, p)
-	return r.relativePath(path.Join(elem...))
+	return r.relativePathFile(path.Join(elem...))
 }
 
 func (r *render) code(code *highlight.Code) template.HTML {

internal/html/render_test.go

@@ -256,6 +256,15 @@ func TestRenderPackage_index(t *testing.T) {
 			}
 		}
 		assert.Equal(t, tt.want, items)
+
+		for _, link := range querySelectorAll(doc, "link") {
+			href := attr(link, "href")
+			if assert.NotEmpty(t, href) {
+				staticPath := "static/" + strings.TrimPrefix(href, "_/")
+				_, err := _staticFS.ReadFile(staticPath)
+				require.NoError(t, err)
+			}
+		}
 	}
 
 	for _, tt := range tests {
@@ -279,6 +288,18 @@ func TestRenderPackage_index(t *testing.T) {
 					Highlighter: _fakeHighlighter,
 				}), tt)
 			})
+
+			t.Run("Standalone with trailing slash", func(t *testing.T) {
+				t.Parallel()
+
+				ensureTrailingSlash := func(s string) string {
+					return strings.TrimSuffix(s, "/") + "/"
+				}
+				runTest(t, (&Renderer{
+					Highlighter:           _fakeHighlighter,
+					NormalizeRelativePath: ensureTrailingSlash,
+				}), tt)
+			})
 		})
 	}
 }