diff --git a/README.md b/README.md index 321855e..064fe55 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ The documentation is built by the static-site-generator [Hugo](https://gohugo.io Clone repository: ```shell -git clone --recurse-submodules git@github.com:cedardb/docs.git +git clone git@github.com:cedardb/docs.git ``` Run a web server: diff --git a/content/clients/psql.md b/content/clients/psql.md index c674feb..d1a8381 100644 --- a/content/clients/psql.md +++ b/content/clients/psql.md @@ -93,7 +93,7 @@ You can also show a list of all tables in the current database: Most commands also have a more verbose variant with a `+` (e.g., `\d+`), which will show more details like the table size in bytes. For a full list of psql backslash commands, see the -[psql docs]((https://www.postgresql.org/docs/current/app-psql.html)). +[psql docs](https://www.postgresql.org/docs/current/app-psql.html). ## Using psql interactively diff --git a/themes/hextra/.devcontainer/devcontainer.json b/themes/hextra/.devcontainer/devcontainer.json index 689ff99..2ae8774 100644 --- a/themes/hextra/.devcontainer/devcontainer.json +++ b/themes/hextra/.devcontainer/devcontainer.json @@ -3,7 +3,7 @@ "features": { "ghcr.io/devcontainers/features/hugo:1": { "extended": true, - "version": "0.119.0" + "version": "0.147.7" }, "ghcr.io/devcontainers/features/node:1": {} }, @@ -18,5 +18,7 @@ } }, "postCreateCommand": "npm install", - "forwardPorts": [1313] -} + "forwardPorts": [ + 1313 + ] +} \ No newline at end of file diff --git a/themes/hextra/.gitattributes b/themes/hextra/.gitattributes new file mode 100644 index 0000000..0820376 --- /dev/null +++ b/themes/hextra/.gitattributes @@ -0,0 +1,3 @@ +# Mark generated files so they are collapsed by default in GitHub diffs +assets/css/compiled/main.css linguist-generated=true +docs/hugo_stats.json linguist-generated=true diff --git a/themes/hextra/.github/CONTRIBUTING.md b/themes/hextra/.github/CONTRIBUTING.md index 3dcf70b..825bb06 100644 --- a/themes/hextra/.github/CONTRIBUTING.md +++ b/themes/hextra/.github/CONTRIBUTING.md @@ -31,7 +31,7 @@ Use [Conventional Commits][conventional commits] message to make it easier to un Similar to contributing code, you can also contribute to the documentation by submitting a pull request. -The documentation site is located in the [`exampleSite`](../exampleSite/) folder. +The documentation site is located in the [`docs`](../docs/) folder. You can make changes to the documentation and create a pull request. A preview of the new documentation will be automatically generated and displayed in the pull request comment via [Netlify][netlify deploy preview]. ### 💬 GitHub Discussions @@ -57,7 +57,7 @@ We recommend that you search existing [issues][issues] or discussions before ope ### Local development setup -- [Hugo][hugo] >= v0.115.0 (extended version) +- [Hugo][hugo] >= v0.124.0 (extended version) - [Node.js][nodejs] - [Go][go] @@ -71,7 +71,7 @@ npm i - [`assets`](../assets/): CSS styles and JavaScript files. - [`data`](../data/): The theme data files. Now only contains the `icons.yaml` file. -- [`exampleSite`](../exampleSite/): The documentation site for the theme. +- [`docs`](../docs/): The documentation site for the theme. - [`i18n`](../i18n/): The theme translation files. - [`layouts`](../layouts/): The theme layouts. - [`static`](../static/): The static files for the theme. For example, the favicon and the site logo. @@ -84,7 +84,7 @@ Please refer to the [Hugo documentation][hugo] for more information. npm run dev:theme ``` -It will start the Hugo server on `http://localhost:1313/` for the `exampleSite` content. +It starts the Hugo server on `http://localhost:1313/` for the `docs` content. ### Compile the styles diff --git a/themes/hextra/.github/FUNDING.yml b/themes/hextra/.github/FUNDING.yml new file mode 100644 index 0000000..b1d6700 --- /dev/null +++ b/themes/hextra/.github/FUNDING.yml @@ -0,0 +1,15 @@ +# These are supported funding model platforms + +github: imfing +patreon: # Replace with a single Patreon username +open_collective: # Replace with a single Open Collective username +ko_fi: # Replace with a single Ko-fi username +tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel +community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry +liberapay: # Replace with a single Liberapay username +issuehunt: # Replace with a single IssueHunt username +lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry +polar: # Replace with a single Polar username +buy_me_a_coffee: # Replace with a single Buy Me a Coffee username +thanks_dev: # Replace with a single thanks.dev username +custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] diff --git a/themes/hextra/.github/ISSUE_TEMPLATE/bug_report.md b/themes/hextra/.github/ISSUE_TEMPLATE/bug_report.md index 48cf2aa..41be0cf 100644 --- a/themes/hextra/.github/ISSUE_TEMPLATE/bug_report.md +++ b/themes/hextra/.github/ISSUE_TEMPLATE/bug_report.md @@ -17,6 +17,8 @@ assignees: '' 2. 3. + + **Expected Behavior** diff --git a/themes/hextra/.github/workflows/pages.yml b/themes/hextra/.github/workflows/pages.yml index df9d55a..c5e98d9 100644 --- a/themes/hextra/.github/workflows/pages.yml +++ b/themes/hextra/.github/workflows/pages.yml @@ -1,5 +1,5 @@ -# Sample workflow for building and deploying a Hugo site to GitHub Pages -name: Deploy Hugo site to Pages +# Build and deploy Hextra docs site to GitHub Pages +name: Deploy Hextra docs site to Pages on: # Runs on pushes targeting the default branch @@ -31,35 +31,43 @@ jobs: build: runs-on: ubuntu-latest env: - HUGO_VERSION: 0.117.0 + HUGO_VERSION: 0.156.0 steps: - name: Checkout uses: actions/checkout@v4 with: - fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + fetch-depth: 0 # fetch all history for .GitInfo and .Lastmod + fetch-tags: true + submodules: recursive + - name: Setup Go - uses: actions/setup-go@v4 + uses: actions/setup-go@v5 with: - go-version: '1.20' + go-version: "1.26" + + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + - name: Setup Hugo - uses: peaceiris/actions-hugo@v2 - with: - hugo-version: ${{ env.HUGO_VERSION }} - extended: true - - name: Build with Hugo + run: | + wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \ + && sudo dpkg -i ${{ runner.temp }}/hugo.deb + + - name: Make build script executable + run: chmod +x ./build.sh + + - name: Build all site versions env: - # For maximum backward compatibility with Hugo modules HUGO_ENVIRONMENT: production HUGO_ENV: production run: | - hugo \ - --minify \ - --themesDir=../.. --source=exampleSite \ - --baseURL "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/" + ./build.sh "${{ steps.pages.outputs.base_url }}" + - name: Upload artifact - uses: actions/upload-pages-artifact@v2 + uses: actions/upload-pages-artifact@v3 with: - path: ./exampleSite/public + path: ./public # Deployment job deploy: @@ -71,4 +79,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v2 + uses: actions/deploy-pages@v4 diff --git a/themes/hextra/.github/workflows/test-accessibility.yml b/themes/hextra/.github/workflows/test-accessibility.yml new file mode 100644 index 0000000..1bd09ef --- /dev/null +++ b/themes/hextra/.github/workflows/test-accessibility.yml @@ -0,0 +1,62 @@ +name: Accessibility Tests + +on: + pull_request: + branches: [main] + +concurrency: + group: accessibility-${{ github.head_ref || github.ref_name }} + cancel-in-progress: true + +defaults: + run: + shell: bash + +jobs: + a11y: + runs-on: ubuntu-latest + environment: accessibility + env: + HUGO_VERSION: 0.156.0 + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + submodules: recursive + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: "1.26" + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: "24" + cache: npm + + - name: Setup Hugo + run: | + wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \ + && sudo dpkg -i ${{ runner.temp }}/hugo.deb + + - name: Install dependencies + run: npm ci + + - name: Install Playwright Chromium + run: npx playwright install chromium + + - name: Build site + run: npm run build + + - name: Run accessibility tests + run: npm run test:a11y + + - name: Upload report + if: always() + uses: actions/upload-artifact@v4 + with: + name: accessibility-report + path: playwright-report/ + retention-days: 14 diff --git a/themes/hextra/.github/workflows/test-mobile-menu.yml b/themes/hextra/.github/workflows/test-mobile-menu.yml new file mode 100644 index 0000000..286fb2f --- /dev/null +++ b/themes/hextra/.github/workflows/test-mobile-menu.yml @@ -0,0 +1,61 @@ +name: Mobile Menu Tests + +on: + pull_request: + branches: [main] + +concurrency: + group: mobile-menu-${{ github.head_ref || github.ref_name }} + cancel-in-progress: true + +defaults: + run: + shell: bash + +jobs: + mobile-menu: + runs-on: ubuntu-latest + env: + HUGO_VERSION: 0.156.0 + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + submodules: recursive + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: "1.26" + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: "24" + cache: npm + + - name: Setup Hugo + run: | + wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \ + && sudo dpkg -i ${{ runner.temp }}/hugo.deb + + - name: Install dependencies + run: npm ci + + - name: Install Playwright Chromium + run: npx playwright install chromium + + - name: Build site + run: npm run build + + - name: Run mobile menu tests + run: npm run test:mobile-menu + + - name: Upload report + if: always() + uses: actions/upload-artifact@v4 + with: + name: mobile-menu-report + path: playwright-report/ + retention-days: 14 diff --git a/themes/hextra/.gitignore b/themes/hextra/.gitignore index 35c3c4e..7377a08 100644 --- a/themes/hextra/.gitignore +++ b/themes/hextra/.gitignore @@ -3,3 +3,7 @@ public/ resources/ .hugo_build.lock + +# Playwright +playwright-report/ +test-results/ diff --git a/themes/hextra/.prettierrc b/themes/hextra/.prettierrc index e0956e4..28eaa1e 100644 --- a/themes/hextra/.prettierrc +++ b/themes/hextra/.prettierrc @@ -1,4 +1,7 @@ { + "plugins": [ + "prettier-plugin-go-template" + ], "goTemplateBracketSpacing": true, "htmlWhitespaceSensitivity": "css", "printWidth": 200, diff --git a/themes/hextra/AGENTS.md b/themes/hextra/AGENTS.md new file mode 100644 index 0000000..c0bbe14 --- /dev/null +++ b/themes/hextra/AGENTS.md @@ -0,0 +1,193 @@ +# AGENTS.md + +This file provides guidance to AI coding agents when working with code in this repository. + +## Project Overview + +Hextra is a modern, responsive Hugo theme designed for creating documentation websites, technical blogs, and static sites. Built with Tailwind CSS, it offers features like full-text search, dark mode, multi-language support, and extensive customization options. + +## Development Commands + +### Initial Setup + +When working in a new worktree or fresh clone without `node_modules`, run `npm install` first to install dependencies: + +```bash +npm install +``` + +### Development Server + +```bash +# Start development server with theme reloading (recommended for theme development) +npm run dev:theme +``` + +### Building + +```bash +# Build the example site +npm run build + +# Build CSS assets only +npm run build:css +``` + +## Architecture Overview + +### Hugo Theme Structure + +- **Base Layout**: `layouts/baseof.html` wraps all pages +- **Specialized Layouts**: `layouts/docs/`, `layouts/blog/`, `layouts/hextra-home.html` +- **Partials**: Reusable components in `layouts/_partials/` + - Core UI: `navbar.html`, `sidebar.html`, `footer.html`, `breadcrumb.html`, `toc.html` + - Utilities: `layouts/_partials/utils/` for helper functions + - Custom overrides: `layouts/_partials/custom/` for user customizations +- **Shortcodes**: Custom Markdown extensions in `layouts/_shortcodes/` +- **Render Hooks**: Custom Markdown rendering in `layouts/_markup/` for codeblocks, headings, images, and links + +### Asset Organization + +``` +assets/ +├── css/ +│ ├── styles.css # Main stylesheet (Tailwind entry point) +│ ├── compiled/main.css # Built CSS output (generated) +│ ├── components/ # Component-specific styles +│ ├── chroma/ # Syntax highlighting themes +│ └── custom.css # User customization entry point +└── js/ + ├── core/ # Core JS components + └── flexsearch.js # Search functionality +``` + +### Key Components + +- **Search**: FlexSearch-powered full-text search (`assets/js/flexsearch.js`) +- **Navigation**: Responsive navbar and auto-generated sidebar +- **Theme Toggle**: Dark/light mode switching +- **Internationalization**: 20+ language support in `i18n/` + +### Content Features + +- **Shortcodes**: `callout`, `card`, `cards`, `tabs`, `tab`, `details`, `steps`, `filetree`, `jupyter`, `badge`, `icon`, `pdf`, `include`, `asciinema`, `term` +- **Code Features**: Syntax highlighting (Chroma), copy buttons, line numbers via render hooks +- **SEO**: Open Graph, Twitter Cards, structured data +- **Performance**: Minimal JavaScript, optimized CSS with Tailwind + +## Development Workflow + +### Example Site Development + +The `docs/` directory serves as both documentation and testing ground: + +- Test new features here before releasing +- Configuration examples in `docs/hugo.yaml` showing multi-language setup +- Content examples demonstrate all theme capabilities +- Run from docs with: `hugo server --themesDir=../..` + +### CSS Development Workflow + +- Source: `assets/css/styles.css` (main stylesheet) +- Build process: Tailwind CSS → PostCSS → `assets/css/compiled/main.css` +- Component styles organized in `assets/css/components/` +- Chroma syntax highlighting themes in `assets/css/chroma/` +- CSS compilation requires Node.js dependencies (PostCSS, Tailwind CSS v4+) + +#### Rebuilding CSS after template changes + +Tailwind CSS relies on `docs/hugo_stats.json` to know which HTML tags, classes, and IDs are actually used in the built site, so it can tree-shake unused styles. When you modify layouts, partials, or shortcodes you must **regenerate `hugo_stats.json` first**, then rebuild the CSS: + +1. **Generate `docs/hugo_stats.json`** — Run Hugo with the `dev.toml` config (which sets `build.buildStats.enable = true`): + + ```bash + # Using npm (starts a dev server that writes hugo_stats.json on every rebuild): + npm run dev:theme + + # Or a one-shot build using the raw Hugo command: + hugo --config=hugo.yaml,../dev.toml --themesDir=../.. --source=docs + ``` + +2. **Build the CSS** — With an up-to-date `hugo_stats.json` in place, compile the stylesheet: + + ```bash + npm run build:css + ``` + +> **Why two steps?** `dev.toml` mounts `docs/hugo_stats.json` into the Hugo asset pipeline (`assets/notwatching/hugo_stats.json`) and configures a cache-buster so that changes to the stats file trigger a CSS recompile during `dev:theme`. When running outside the dev server you need to perform these steps manually in order. + +### Customization Points + +- Custom partials: `layouts/_partials/custom/` +- Custom CSS: `assets/css/custom.css` +- Site-specific overrides: Copy any layout to your site's `layouts/` directory + +## Configuration & Requirements + +### Theme Requirements + +- Hugo minimum version: 0.146.0 (extended version required - see `theme.toml`) +- Go 1.20+ (as specified in `go.mod`) +- Node.js for CSS compilation (PostCSS, Tailwind CSS v4+) + +### Key Configuration Files + +- `docs/hugo.yaml` - Example Hugo configuration with multi-language setup +- `postcss.config.mjs` - PostCSS configuration for CSS processing +- `package.json` - Node.js dependencies and build scripts + +### Development Environment + +- Default Hugo development server: Port 1313 +- Development server runs with `--disableFastRender -D` for better development experience +- Theme development uses `--logLevel=debug` for detailed logging + +### Multi-language Support + +- Configure languages in `hugo.yaml` (supports 20+ languages including RTL) +- Translation files in `i18n/` directory (e.g., `en.yaml`, `fa.yaml`, `ja.yaml`, `zh-cn.yaml`) +- Example supports English, Persian (RTL), Japanese, and Simplified Chinese + +## Theme Development Guidelines + +### Hugo Theme Conventions + +- Theme files in this repository override Hugo defaults +- Follow Hugo's theme development guidelines for compatibility +- Maintain backward compatibility with existing configurations + +### JavaScript & Performance + +- All JavaScript components are designed to have minimal footprint +- Core JS components in `assets/js/core/`: `theme.js`, `nav-menu.js`, `code-copy.js`, `sidebar.js`, `tabs.js`, etc. +- FlexSearch powers offline full-text search (`assets/js/flexsearch.js`) + +### CSS Architecture + +- Uses Tailwind CSS v4+ with PostCSS processing +- Component-based CSS organization in `assets/css/components/` +- Compiled output goes to `assets/css/compiled/main.css` +- Prettier formatting for Go templates and code consistency + +### Accessibility (WCAG Compliance) + +All new features and UI changes must follow the [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) at the **AA** conformance level. Key requirements: + +- **Semantic HTML**: Use appropriate elements (`