docs: add interactive documentation system with Go+HTMX
- Add internal/docs package with markdown renderer (goldmark) - Create docs layout template with sidebar navigation - Implement hierarchical navigation auto-generated from docs folder - Add table of contents generator (extract ## headings) - Add syntax highlighting for code blocks (highlight.js) - Add mobile responsive design - Add /docs routes to main.go The documentation system features: - Dark theme matching app design - Collapsible sidebar sections (Getting Started, User Guide, Device Setup, API Reference, Contributing) - Table of contents for each page - Breadcrumb navigation - Full-text search (client-side JavaScript, API endpoint ready) - Syntax highlighting for code blocks - Mobile-friendly with hamburger menu All documentation is served from /docs route, no authentication required. Markdown files are rendered using goldmark with GFM extensions and syntax highlighting.
This commit is contained in:
@@ -0,0 +1,268 @@
|
||||
package docs
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"strings"
|
||||
|
||||
"bookhoard/templates"
|
||||
"github.com/labstack/echo/v4"
|
||||
)
|
||||
|
||||
// HTTPHandler wraps the docs handler for Echo framework
|
||||
type HTTPHandler struct {
|
||||
docs *DocsHandler
|
||||
}
|
||||
|
||||
// NewHTTPHandler creates a new docs HTTP handler
|
||||
func NewHTTPHandler(docsPath string) *HTTPHandler {
|
||||
return &HTTPHandler{
|
||||
docs: NewDocsHandler(docsPath),
|
||||
}
|
||||
}
|
||||
|
||||
// ShowDocumentation renders a documentation page
|
||||
func (h *HTTPHandler) ShowDocumentation(c echo.Context) error {
|
||||
// Get the document path from URL parameter
|
||||
docPath := c.Param("*")
|
||||
|
||||
// Load the document
|
||||
doc, err := h.docs.LoadDocument(docPath)
|
||||
if err != nil {
|
||||
// Try to load as API endpoint
|
||||
if strings.HasPrefix(docPath, "api/") {
|
||||
return h.ShowAPIEndpoint(c, strings.TrimPrefix(docPath, "api/"))
|
||||
}
|
||||
|
||||
// Return error page
|
||||
errorHTML := fmt.Sprintf(`<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Document Not Found - Bookhoard</title>
|
||||
<script src="https://cdn.tailwindcss.com"></script>
|
||||
</head>
|
||||
<body class="bg-gray-900 text-gray-100 min-h-screen flex items-center justify-center">
|
||||
<div class="text-center">
|
||||
<h1 class="text-2xl font-bold mb-4">Document Not Found</h1>
|
||||
<p class="mb-4">%s</p>
|
||||
<a href="/docs" class="text-blue-400 hover:underline">Return to Documentation</a>
|
||||
</div>
|
||||
</body>
|
||||
</html>`, err.Error())
|
||||
|
||||
return c.HTML(http.StatusNotFound, errorHTML)
|
||||
}
|
||||
|
||||
// Get navigation
|
||||
nav := h.docs.BuildNavigation()
|
||||
|
||||
// Create empty user (docs are public, no auth required)
|
||||
user := templates.User{
|
||||
ID: "",
|
||||
Username: "",
|
||||
Email: "",
|
||||
Role: "",
|
||||
Theme: "tokyo-night",
|
||||
}
|
||||
|
||||
// Render documentation page
|
||||
var buf bytes.Buffer
|
||||
err = templates.DocsLayout(*nav, *doc, user).Render(c.Request().Context(), &buf)
|
||||
if err != nil {
|
||||
fmt.Printf("DOCS RENDER ERROR: %v\n", err)
|
||||
return c.HTML(http.StatusInternalServerError, "Failed to render page: "+err.Error())
|
||||
}
|
||||
fmt.Printf("DOCS: Successfully rendered %s (%d bytes)\n", docPath, buf.Len())
|
||||
return c.HTML(http.StatusOK, buf.String())
|
||||
}
|
||||
|
||||
// ShowAPIEndpoint shows a specific API endpoint documentation
|
||||
func (h *HTTPHandler) ShowAPIEndpoint(c echo.Context, endpointPath string) error {
|
||||
endpoints := h.docs.GetAPIEndpoints()
|
||||
|
||||
// Find the endpoint
|
||||
var foundEndpoint *APIEndpoint
|
||||
for _, ep := range endpoints {
|
||||
if strings.HasSuffix(endpointPath, strings.TrimPrefix(ep.Path, "/api/")) {
|
||||
foundEndpoint = &ep
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if foundEndpoint == nil {
|
||||
errorHTML := `<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>API Endpoint Not Found - Bookhoard</title>
|
||||
<script src="https://cdn.tailwindcss.com"></script>
|
||||
</head>
|
||||
<body class="bg-gray-900 text-gray-100 min-h-screen flex items-center justify-center">
|
||||
<div class="text-center">
|
||||
<h1 class="text-2xl font-bold mb-4">API Endpoint Not Found</h1>
|
||||
<a href="/docs/api" class="text-blue-400 hover:underline">Return to API Documentation</a>
|
||||
</div>
|
||||
</body>
|
||||
</html>`
|
||||
|
||||
return c.HTML(http.StatusNotFound, errorHTML)
|
||||
}
|
||||
|
||||
// Get navigation
|
||||
nav := h.docs.BuildNavigation()
|
||||
|
||||
// Create empty user
|
||||
user := templates.User{
|
||||
ID: "",
|
||||
Username: "",
|
||||
Email: "",
|
||||
Role: "",
|
||||
Theme: "tokyo-night",
|
||||
}
|
||||
|
||||
// Render API endpoint page
|
||||
var buf bytes.Buffer
|
||||
err := templates.DocsLayout(*nav, templates.Document{
|
||||
Title: foundEndpoint.Title,
|
||||
Content: fmt.Sprintf("<p>Documentation for <code>%s %s</code></p>", foundEndpoint.Method, foundEndpoint.Path),
|
||||
TOC: []templates.TOCItem{},
|
||||
Breadcrumb: []templates.BreadcrumbItem{
|
||||
{Title: "Docs", URL: "/docs"},
|
||||
{Title: "API Reference", URL: "/docs/api"},
|
||||
{Title: foundEndpoint.Category, URL: "/docs/api"},
|
||||
{Title: foundEndpoint.Title, URL: ""},
|
||||
},
|
||||
Category: "API Reference",
|
||||
SourceFile: "api",
|
||||
}, user).Render(c.Request().Context(), &buf)
|
||||
|
||||
if err != nil {
|
||||
return c.HTML(http.StatusInternalServerError, "Failed to render page")
|
||||
}
|
||||
|
||||
return c.HTML(http.StatusOK, buf.String())
|
||||
}
|
||||
|
||||
// DocsHome redirects to the documentation index
|
||||
func (h *HTTPHandler) DocsHome(c echo.Context) error {
|
||||
return c.Redirect(http.StatusFound, "/docs/INDEX.md")
|
||||
}
|
||||
|
||||
// APIHome shows the API documentation home page
|
||||
func (h *HTTPHandler) APIHome(c echo.Context) error {
|
||||
endpoints := h.docs.GetAPIEndpoints()
|
||||
nav := h.docs.BuildNavigation()
|
||||
|
||||
user := templates.User{
|
||||
ID: "",
|
||||
Username: "",
|
||||
Email: "",
|
||||
Role: "",
|
||||
Theme: "tokyo-night",
|
||||
}
|
||||
|
||||
// Build API documentation content
|
||||
content := "<h2>API Endpoints</h2><p>Complete API reference for Bookhoard v1.0.</p><ul>"
|
||||
for _, ep := range endpoints {
|
||||
content += fmt.Sprintf(`<li><a href="/docs/api%s"><strong>%s %s</strong></a> - %s</li>`,
|
||||
strings.TrimPrefix(ep.Path, "/api"),
|
||||
ep.Method,
|
||||
ep.Path,
|
||||
ep.Title,
|
||||
)
|
||||
}
|
||||
content += "</ul>"
|
||||
|
||||
apiDoc := &templates.Document{
|
||||
Title: "API Reference",
|
||||
Content: content,
|
||||
TOC: []templates.TOCItem{},
|
||||
Breadcrumb: []templates.BreadcrumbItem{
|
||||
{Title: "Docs", URL: "/docs"},
|
||||
{Title: "API Reference", URL: ""},
|
||||
},
|
||||
Category: "API Reference",
|
||||
SourceFile: "API_REFERENCE.md",
|
||||
}
|
||||
|
||||
var buf bytes.Buffer
|
||||
err := templates.DocsLayout(*nav, *apiDoc, user).Render(c.Request().Context(), &buf)
|
||||
|
||||
if err != nil {
|
||||
return c.HTML(http.StatusInternalServerError, "Failed to render page")
|
||||
}
|
||||
|
||||
return c.HTML(http.StatusOK, buf.String())
|
||||
}
|
||||
|
||||
// Search searches through documentation
|
||||
func (h *HTTPHandler) Search(c echo.Context) error {
|
||||
query := c.QueryParam("q")
|
||||
if query == "" {
|
||||
return c.JSON(http.StatusBadRequest, map[string]string{
|
||||
"error": "query parameter 'q' is required",
|
||||
})
|
||||
}
|
||||
|
||||
// Get all documents
|
||||
docs, err := h.docs.ListDocuments()
|
||||
if err != nil {
|
||||
return c.JSON(http.StatusInternalServerError, map[string]string{
|
||||
"error": "failed to list documents",
|
||||
})
|
||||
}
|
||||
|
||||
// Simple search implementation
|
||||
var results []SearchResult
|
||||
queryLower := strings.ToLower(query)
|
||||
|
||||
for _, docPath := range docs {
|
||||
doc, err := h.docs.LoadDocument(docPath)
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
|
||||
// Check if title matches
|
||||
if strings.Contains(strings.ToLower(doc.Title), queryLower) {
|
||||
results = append(results, SearchResult{
|
||||
Title: doc.Title,
|
||||
URL: "/docs/" + strings.TrimSuffix(doc.SourceFile, ".md"),
|
||||
Type: "Documentation",
|
||||
})
|
||||
continue
|
||||
}
|
||||
|
||||
// Check if content matches (simple substring search)
|
||||
contentLower := strings.ToLower(doc.Content)
|
||||
if strings.Contains(contentLower, queryLower) {
|
||||
results = append(results, SearchResult{
|
||||
Title: doc.Title,
|
||||
URL: "/docs/" + strings.TrimSuffix(doc.SourceFile, ".md"),
|
||||
Type: "Documentation",
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
return c.JSON(http.StatusOK, map[string]interface{}{
|
||||
"results": results,
|
||||
"count": len(results),
|
||||
})
|
||||
}
|
||||
|
||||
// SearchResult represents a search result
|
||||
type SearchResult struct {
|
||||
Title string
|
||||
URL string
|
||||
Type string
|
||||
}
|
||||
|
||||
// TryEndpoint executes an API endpoint (for the interactive explorer)
|
||||
func (h *HTTPHandler) TryEndpoint(c echo.Context) error {
|
||||
// This would execute the actual API request
|
||||
// For now, return a placeholder
|
||||
return c.JSON(http.StatusOK, map[string]interface{}{
|
||||
"message": "API explorer not yet implemented",
|
||||
})
|
||||
}
|
||||
Reference in New Issue
Block a user