{"id":28229158,"url":"https://github.com/qualityunit/hugo-boilerplate","last_synced_at":"2026-02-21T11:31:03.135Z","repository":{"id":285907218,"uuid":"956458661","full_name":"QualityUnit/hugo-boilerplate","owner":"QualityUnit","description":"Template for hugo projects","archived":false,"fork":false,"pushed_at":"2026-02-16T15:01:36.000Z","size":8861,"stargazers_count":1,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-16T16:33:33.137Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/QualityUnit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-28T09:39:09.000Z","updated_at":"2026-02-16T08:58:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"40a6667d-6f5c-4b6e-a49e-9498d9d6478c","html_url":"https://github.com/QualityUnit/hugo-boilerplate","commit_stats":null,"previous_names":["qualityunit/hugo-boilerplate"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/QualityUnit/hugo-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QualityUnit%2Fhugo-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QualityUnit%2Fhugo-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QualityUnit%2Fhugo-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QualityUnit%2Fhugo-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QualityUnit","download_url":"https://codeload.github.com/QualityUnit/hugo-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QualityUnit%2Fhugo-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29679786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T11:29:27.227Z","status":"ssl_error","status_checked_at":"2026-02-21T11:29:20.292Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-18T15:13:41.823Z","updated_at":"2026-02-21T11:31:03.125Z","avatar_url":"https://github.com/QualityUnit.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hugo Boilerplate Theme\n\nA clean and minimal Hugo theme designed for QualityUnit websites with a focus on performance, SEO, and responsive design. \nThis theme includes Tailwind CSS integration, comprehensive SEO features, responsive image processing, and multilingual support out of the box.\n\n\n## Projects running this theme\n- [AiMingle](https://www.aimingle.cz/) - https://github.com/QualityUnit/aimingle-hugo\n- [FlowHunt](https://www.flowhunt.io/) - https://github.com/QualityUnit/flowhunt-hugo\n- [Post Affiliate Pro](https://main.d1jnujto7ausyo.amplifyapp.com/) - https://github.com/QualityUnit/postaffiliatepro-hugo\n- [UrlsLab](https://www.urlslab.com/) - https://github.com/QualityUnit/urlslab-hugo\n- [PhotomaticAI](https://www.photomaticai.com/) - https://github.com/QualityUnit/photomaticai-hugo/\n- [Wachman](https://www.wachman.eu) - https://github.com/vzeman/wachman\n\n## Notes For developers\n- Many partials and shortcodes are not correct, we need to fix them.\n- If shortcode or partial is used already in any project, always make sure your changes are compatible with old data, new parameters needs to be optional\n- Make sure all texts can be translated, add texts to translation files in theme\n\n## Features\n\n- **Tailwind CSS Integration** - we have bought license from [https://tailwindcss.com/plus/ui-blocks/marketing](https://tailwindcss.com/plus/ui-blocks/marketing), we should try to keep the similar naming convention for our own elements\n- **Responsive Design** - Optimized for all device sizes\n- **Multilingual Support** - Built-in support for multiple languages\n- **SEO Optimized** - Preprocessing of data done by `scripts/build_content.sh` script (linkbuilding, relations of content, image preprocessing, attributes syncing)\n- **Responsive Images** - Automatic image processing with WebP conversion (`scripts/build_content.sh`)\n- **Lazy Loading** - Performance-optimized image and video loading (shorcode `lazyimg` should be used in markdown and in partials)\n- **Glossary System** - Built-in glossary with alphabetical navigation - this is just example post type, we can add more post types to share them accross projects\n- **Tag \u0026 Category System** - Comprehensive taxonomy management, custom taxonomies are allowed per domain\n- **Component Library** - Extensive collection of pre-built components:\n  - Headers and navigation menus\n  - Product showcases and listings\n  - Feature sections\n  - Review components\n  - Banners and CTAs\n\n## Content Preparation Scripts\n\nThe theme includes a comprehensive set of scripts in the `scripts/` directory that prepare your content for optimal performance and SEO.\n\n### Main Script: build_content.sh\n\nThis is the primary script that coordinates the entire content preparation process:\n\n```bash\n# Run from the Hugo site root\n./themes/boilerplate/scripts/build_content.sh\n```\n\n#### What build_content.sh Does:\n\n1. **Sets up environment**: Creates a Python virtual environment and installs required dependencies\n2. **Syncs translations**: Ensures translation keys are consistent across language files\n3. **Builds Hugo site**: Validates content by building the entire site (exits on errors)\n4. **Offloads images**: Downloads and stores images from external sources if needed\n5. **Finds duplicate images**: Identifies duplicate images across the project\n6. **Translates missing content**: Uses the FlowHunt API to translate missing content files\n7. **Synchronizes attributes**: Ensures content attributes are consistent across translations\n8. **Generates translation URLs**: Creates URL mapping for all languages\n9. **Generates related content**: Creates YAML files for internal linking\n10. **Extracts automatic links**: Extracts keywords from frontmatter for linkbuilding (first 2 keywords per page)\n11. **Precomputes linkbuilding**: Optimizes keyword files based on actual content\n    - **Incremental processing**: Only processes languages without existing optimized files\n    - **Force recomputation**: Delete specific `*_optimized.json` files to recompute those languages\n    - **Force all**: Use `--force` flag to recompute all languages\n12. **Preprocesses images**: Optimizes images for web delivery (WebP conversion, responsive sizes)\n\n#### Running Specific Steps:\n\nYou can run specific parts of the build process using the `--step` flag:\n\n```bash\n# Run only image preprocessing\n./themes/boilerplate/scripts/build_content.sh --step preprocess_images\n\n# Run multiple steps\n./themes/boilerplate/scripts/build_content.sh --step sync_translations,validate_content\n```\n\nAvailable steps:\n- `sync_translations`: Synchronize translation keys across files\n- `build_hugo`: Build and validate Hugo site (exits on errors)\n- `offload_images`: Download images from external services\n- `find_duplicate_images`: Find and report duplicate images\n- `translate`: Translate missing content with FlowHunt API\n- `sync_content_attributes`: Ensure content attribute consistency\n- `generate_translation_urls`: Generate URL mappings for all languages\n- `generate_related_content`: Create related content data\n- `extract_automatic_links`: Extract keywords from frontmatter for linkbuilding\n- `precompute_linkbuilding`: Optimize linkbuilding files based on actual content\n- `apply_linkbuilding`: Apply linkbuilding to HTML files in public folder\n- `preprocess_images`: Optimize images for web delivery\n\n#### Requirements:\n\n- Python 3.8+ with pip\n- FlowHunt API key (for translation functionality)\n- Image processing tools (handled by the script)\n\nThe script will prompt for a FlowHunt API key if not already configured.\n\n### Linkbuilding Optimization\n\nThe linkbuilding system includes smart optimization features:\n\n#### Incremental Processing\nThe `precompute_linkbuilding` step only processes languages that don't have optimized files yet:\n- Automatically skips languages with existing `*_optimized.json` files\n- Significantly speeds up repeated builds\n- Only recomputes when content changes\n\n#### Force Recomputation\nTo recompute specific languages:\n```bash\n# Method 1: Delete the optimized file for that language\nrm data/linkbuilding/optimized/de_optimized.json\n./themes/boilerplate/scripts/build_content.sh --step precompute_linkbuilding\n\n# Method 2: Use force flag for specific languages\nthemes/boilerplate/scripts/.venv/bin/python themes/boilerplate/scripts/precompute_linkbuilding.py \\\n  --linkbuilding-dir data/linkbuilding \\\n  --public-dir public \\\n  --output-dir data/linkbuilding/optimized \\\n  --force-languages de fr es\n\n# Method 3: Force all languages\nthemes/boilerplate/scripts/.venv/bin/python themes/boilerplate/scripts/precompute_linkbuilding.py \\\n  --linkbuilding-dir data/linkbuilding \\\n  --public-dir public \\\n  --output-dir data/linkbuilding/optimized \\\n  --force\n```\n\n#### Performance Features\n- Processes 3 languages in parallel by default (configurable with `--parallel-languages`)\n- Skips unnecessary files (categories, tags, pagination)\n- Early stopping when all keywords are found\n- Deduplicates case-insensitive keywords automatically\n\n## Installation\n\n### Option 1: As a Git Submodule (Recommended)\n\nThis method allows you to easily update the theme when new versions are released:\n\n```bash\n# Navigate to your Hugo site's root directory\ncd your-hugo-site\n\n# Add the theme as a submodule\ngit submodule add https://github.com/qualityunit/hugo-boilerplate.git themes/boilerplate\n\n# Update your Hugo configuration to use the theme\necho 'theme = \"boilerplate\"' \u003e\u003e hugo.toml\n```\n\n### Option 2: Manual Download\n\nIf you prefer not to use Git submodules:\n\n```bash\n# Navigate to your Hugo site's root directory\ncd your-hugo-site\n\n# Download the theme\nmkdir -p themes\ncurl -L https://github.com/owner/hugo-boilerplate/archive/main.tar.gz | tar -xz -C themes\nmv themes/hugo-boilerplate-main themes/boilerplate\n\n# Update your Hugo configuration to use the theme\necho 'theme = \"boilerplate\"' \u003e\u003e hugo.toml\n```\n\n## Dependencies\n\nThis theme requires Node.js and npm for build process orchestration. The project uses Gulp for task management, Tailwind CSS for styling, and ESBuild for JavaScript bundling.\n\nYou need to create a `package.json` file in your project root (not in the theme directory) with the necessary dependencies.\n\n### Required Dependencies\n\n```json\n{\n  \"name\": \"your-project-name\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Your project description\",\n  \"scripts\": {\n    \"start\": \"gulp\",\n    \"dev\": \"gulp dev\",\n    \"watch\": \"gulp watch\",\n    \"build\": \"gulp css \u0026\u0026 gulp js\"\n  },\n  \"devDependencies\": {\n    \"@tailwindcss/aspect-ratio\": \"^0.4.2\",\n    \"@tailwindcss/forms\": \"^0.5.7\",\n    \"@tailwindcss/typography\": \"^0.5.10\",\n    \"autoprefixer\": \"^10.4.21\",\n    \"cssnano\": \"^7.0.7\",\n    \"esbuild\": \"^0.25.5\",\n    \"gulp\": \"^5.0.1\",\n    \"gulp-postcss\": \"^10.0.0\",\n    \"postcss\": \"^8.4.31\",\n    \"postcss-cli\": \"^10.1.0\",\n    \"postcss-import\": \"^16.1.0\",\n    \"tailwindcss\": \"^3.4.17\",\n    \"yargs\": \"^18.0.0\"\n  }\n}\n```\n\n### Build System Overview\n\nThe theme uses a Gulp-based build system that:\n\n1. **CSS Processing**: \n   - Processes CSS `@import` statements with postcss-import\n   - Compiles Tailwind CSS with PostCSS\n   - Adds vendor prefixes with autoprefixer\n   - Minifies output with cssnano\n2. **JavaScript Bundling**: Uses ESBuild for fast bundling and minification\n3. **Watch Mode**: Provides live reloading during development\n4. **Hugo Integration**: Automatically starts Hugo server with configurable options\n\n### Gulpfile Configuration\n\nThe build system requires a `gulpfile.js` in your project root:\n\n```javascript\nconst gulp = require('gulp');\nconst postcss = require('gulp-postcss');\nconst postcssImport = require('postcss-import');\nconst tailwindcss = require('tailwindcss');\nconst autoprefixer = require('autoprefixer');\nconst esbuild = require('esbuild');\nconst { spawn } = require('child_process');\nconst cssnano = require('cssnano');\nconst yargs = require('yargs/yargs');\nconst { hideBin } = require('yargs/helpers');\n\n// CSS and JS source paths\nconst cssSrc = 'themes/boilerplate/assets/css/main.css';\nconst cssDest = 'static/css';\nconst jsEntryPoints = ['themes/boilerplate/assets/js/main.js'];\nconst jsDest = 'static/js';\n\n// CSS build with @import processing\nfunction buildCSS() {\n    return gulp.src(cssSrc)\n        .pipe(postcss([\n            postcssImport,    // Process @import statements first\n            tailwindcss,\n            autoprefixer,\n            cssnano()\n        ]))\n        .pipe(gulp.dest(cssDest));\n}\n\n// Build tasks and configuration...\n```\n\n## PostCSS Configuration\n\n### Required Setup\n\nThis theme uses Tailwind CSS which is processed through Gulp and PostCSS. You **must** create a `postcss.config.js` file in your project root (not in the theme directory) with the following content:\n\n```javascript\n// postcss.config.js in your project root\nmodule.exports = {\n  plugins: {\n    tailwindcss: {},\n    autoprefixer: {},\n  },\n};\n```\n\n### Tailwind Configuration\n\nThe theme includes a pre-configured `tailwind.config.js` that:\n\n1. Scans the correct template directories for class usage\n2. Includes necessary Tailwind plugins\n3. Provides custom color schemes and utilities\n\n```javascript\n// tailwind.config.js example\nmodule.exports = {\n    darkMode: 'class',\n    content: [\n        './layouts/**/*.html',\n        './themes/boilerplate/layouts/**/*.html', \n        './themes/boilerplate/assets/js/**/*.js',\n    ],\n    theme: {\n        extend: {\n            // Custom theme extensions\n        },\n    },\n    plugins: [\n        require('@tailwindcss/typography'),\n        require('@tailwindcss/forms'),\n        require('@tailwindcss/aspect-ratio'),\n    ],\n};\n```\n\n### Build Process Integration\n\nThe Gulp build system automatically:\n\n1. **Processes @import statements**: Uses postcss-import to inline imported CSS files\n2. **Compiles Tailwind CSS**: Runs Tailwind CSS compilation with PostCSS\n3. **Applies Autoprefixer**: Adds vendor prefixes for browser compatibility  \n4. **Minifies Output**: Uses cssnano for production-ready CSS\n5. **Watches Changes**: Rebuilds CSS when source files change\n\n### CSS Import System\n\nThe theme supports CSS imports in the main CSS file:\n\n```css\n/* themes/boilerplate/assets/css/main.css */\n@import \"./fonts.css\";\n@import \"./typewriter.css\";\n@import \"./lazy-images.css\";\n@import \"./lazy-videos.css\";\n\n@tailwind base;\n@tailwind components;\n@tailwind utilities;\n```\n\nThe `postcss-import` plugin automatically inlines these imports during the build process, creating a single minified CSS file in `static/css/main.css`.\n\n## JavaScript Bundling with ESBuild\n\nThe theme uses ESBuild for fast JavaScript bundling and processing:\n\n### ESBuild Configuration\n\nJavaScript files are processed with the following settings:\n\n- **Entry Points**: `themes/boilerplate/assets/js/main.js`\n- **Output**: `static/js/` directory\n- **Format**: IIFE (Immediately Invoked Function Expression)\n- **Bundling**: Enabled for dependency resolution\n- **Minification**: Enabled for production builds\n- **Watch Mode**: Available for development\n\n### JavaScript Development\n\n1. **Main Entry**: Place your JavaScript in `themes/boilerplate/assets/js/main.js`\n2. **Modules**: Import ES6 modules normally - ESBuild handles bundling\n3. **Build**: Run `gulp js` or `npm run build` to process JavaScript\n4. **Watch**: Use `gulp dev` for automatic rebuilding during development\n\n### JavaScript Build Process\n\n```javascript\n// gulpfile.js JavaScript task example\nfunction buildJS() {\n    return esbuild.build({\n        entryPoints: ['themes/boilerplate/assets/js/main.js'],\n        bundle: true,\n        minify: true,\n        format: 'iife',\n        outdir: 'static/js'\n    });\n}\n```\n\n### Troubleshooting Build Issues\n\nIf you encounter build errors:\n\n1. **Verify Dependencies**: Ensure all npm packages are installed correctly with `npm install`\n2. **Check File Paths**: Confirm Tailwind content paths match your project structure\n3. **Gulp Configuration**: Verify gulpfile.js is properly configured with all required plugins\n4. **PostCSS Config**: Ensure postcss.config.js exists in project root\n5. **CSS Import Errors**: Check that imported CSS files exist in the correct paths relative to main.css\n\n**Common Issues:**\n\n- **MIME type errors**: Usually resolved by properly configuring postcss-import plugin\n- **Missing CSS files**: Ensure all @import paths are correct and files exist\n- **Build failures**: Check that all dependencies are installed and paths are correct\n\n## Configuration\n\n### Basic Configuration\n\nThis theme supports two configuration approaches:\n\n#### Option 1: Using a Single Configuration File (Traditional)\n\nAdd the following to your `hugo.toml` file:\n\n```toml\nbaseURL = 'https://example.com/'\nlanguageCode = 'en-us'\ntitle = 'Your Site Title'\ntheme = 'boilerplate'\ndefaultContentLanguage = \"en\"\ndefaultContentLanguageInSubdir = true\n\n# Output formats configuration\n[outputs]\n  home = [\"HTML\", \"RSS\", \"SITEMAP\"]\n\n# Site parameters\n[params]\n  description = \"Your site description\"\n  author = \"Your Name\"\n  mainSections = [\"blog\"]\n  dateFormat = \"January 2, 2006\"\n```\n\n#### Option 2: Using Split Configuration Files (Recommended)\n\nFor better organization, you can split your configuration into multiple files in a `config/_default/` directory:\n\n1. Copy the example configuration structure from the theme:\n\n```bash\nmkdir -p config/_default\ncp -r themes/boilerplate/config_example/_default/* config/_default/\n```\n\n2. Edit the individual configuration files to customize your site:\n   - `hugo.toml` - Basic site configuration\n   - `languages.toml` - Multilingual settings\n   - `menus.toml` - Navigation menu structure\n   - `params.toml` - Site parameters and features\n   - `outputFormats.toml` - Output format configuration\n   - `markup.toml` - Content rendering settings\n   - `module.toml` - Hugo modules configuration\n\nThis modular approach makes your configuration more maintainable, especially for complex sites.\n\n### Multilingual Setup\n\nThe theme supports multiple languages out of the box. Configure them in `languages.toml` (if using split configuration) or in your `hugo.toml` under the `[languages]` section:\n\n```toml\n[languages]\n  [languages.en]\n    languageName = \"English\"\n    title = \"English Site Title\"\n    weight = 1\n    contentDir = \"content/en\"\n    baseURL = \"https://example.com\"\n    [languages.en.params]\n      bcp47Lang = \"en-us\"\n      description = \"English site description\"\n\n  [languages.de]\n    languageName = \"Deutsch\"\n    title = \"Deutsche Site Title\"\n    weight = 2\n    contentDir = \"content/de\"\n    baseURL = \"https://example.de\"\n    [languages.de.params]\n      bcp47Lang = \"de\"\n      description = \"Deutsche Seitenbeschreibung\"\n```\n\n### Menu Configuration\n\nDefine your site's navigation in `menus.toml` (if using split configuration) or in your `hugo.toml` under language-specific menu sections:\n\n```toml\n[languages.en.menu]\n  [[languages.en.menu.main]]\n    identifier = \"home\"\n    name = \"Home\"\n    url = \"/\"\n    weight = 1\n  [[languages.en.menu.main]]\n    identifier = \"blog\"\n    name = \"Blog\"\n    \n    weight = 2\n```\n\n### Image Processing Configuration\n\nFor optimal image processing, add the following to your `params.toml` (if using split configuration) or to the `[params]` section of your `hugo.toml`:\n\n```toml\n[params.imaging]\n  resampleFilter = \"Lanczos\"\n  quality = 85\n  anchor = \"smart\"\n  bgColor = \"#ffffff\"\n  webpQuality = 85\n```\n\n## Content Structure\n\n### Creating Blog Posts\n\nCreate a new blog post with:\n\n```bash\nhugo new content/en/blog/my-post.md\n```\n\nFront matter example:\n\n```yaml\n+++\ntitle = 'My Post Title'\ndate = 2025-04-03T07:43:16+02:00\n\ndescription = \"A comprehensive description for SEO purposes\"\nkeywords = [\"keyword1\", \"keyword2\", \"keyword3\"]\nimage = \"/images/blog/featured-image.jpg\"\ntags = [\"tag1\", \"tag2\"]\ncategories = [\"category1\"]\n+++\n\nYour post content here...\n```\n\n### Creating Glossary Terms\n\nCreate a new glossary term with:\n\n```bash\nhugo new content/en/glossary/term-name.md\n```\nor just create the file in the `content/en/glossary/` directory with extension *.md.\n\n\nFront matter example:\n\n```yaml\n+++\ntitle = 'Term Name'\ndate = 2025-04-03T07:43:16+02:00\n\nurl = \"glossary/term-name\"\ndescription = \"A comprehensive description of the term for SEO purposes\"\nkeywords = [\"keyword1\", \"keyword2\", \"keyword3\"]\nimage = \"/images/glossary/term-image.jpg\"\nterm = \"Term Name\"\nshortDescription = \"A brief description of the term\"\ncategory = \"T\"\ntags = [\"tag1\", \"tag2\"]\nadditionalImages = [\n  \"/images/glossary/additional-image1.jpg\",\n  \"/images/glossary/additional-image2.jpg\"\n]\n\n# CTA Section Configuration\nshowCTA = true\nctaHeading = \"Related CTA Heading\"\nctaDescription = \"Call to action description text\"\nctaPrimaryText = \"Primary Button\"\nctaPrimaryURL = \"/related-url/\"\nctaSecondaryText = \"Secondary Button\"\nctaSecondaryURL = \"/another-url/\"\n\n[[faq]]\nquestion = \"Frequently asked question about the term?\"\nanswer = \"Comprehensive answer to the question that provides valuable information about the term.\"\n+++\n\n# What is Term Name?\n\nMain content about the term goes here...\n```\n\n## Automatic Linkbuilding\n\nThe theme provides an automatic linkbuilding feature that scans your content and replaces specified keywords with links. This is configured via YAML files in the `data/linkbuilding/` directory, with a separate file for each language (e.g., `en.yaml`, `de.yaml`).\n\n### Configuration File Structure\n\nEach language-specific YAML file should contain a list of `keywords`. Each keyword entry defines the term to be linked, the target URL, and other options.\n\nHere's an example from `data/linkbuilding/en.yaml`:\n\n```yaml\nkeywords:\n  - keyword: \"mcp\"\n    url: \"/services/mcp-server-development/\"\n    exact: false\n    priority: 1\n    title: \"We can develop and host your own MCP server\"\n  - keyword: \"mcp server\"\n    url: \"/services/mcp-server-development/\"\n    exact: false\n    priority: 1\n    title: \"We can develop and host your own MCP server\"\n  - keyword: \"mcp servers\"\n    url: \"/services/mcp-server-development/\"\n    exact: false\n    priority: 1\n    title: \"We can develop and host your own MCP server\"\n```\n\n### Keyword Entry Fields:\n\n-   `keyword`: (String) The actual word or phrase in your content that you want to turn into a link. The matching is case-insensitive by default.\n-   `url`: (String) The destination URL for the link. This should typically be a site-relative path (e.g., `/services/your-service/`).\n-   `exact`: (Boolean, optional, defaults to `false`) \n    -   If `false` (default): The keyword will be matched even if it's part of a larger word (e.g., if keyword is \"log\", \"logging\" would also be matched). The matching is case-insensitive.\n    -   If `true`: The keyword will only be matched if it appears as an exact word (bounded by spaces or punctuation). The matching is case-sensitive.\n-   `priority`: (Integer, optional, defaults to `1`) Used to determine which rule applies if multiple keywords could match the same text. Higher numbers usually mean higher priority. The linkbuilding module processes keywords based on their priority, with higher priority keywords being applied first.\n-   `title`: (String, optional, defaults to the `keyword` value) The text to be used for the `title` attribute of the generated `\u003ca\u003e` HTML tag. This is often used for tooltips or to provide more context to search engines.\n\nTo add new linkbuilding rules, simply edit the appropriate `data/linkbuilding/\u003clang\u003e.yaml` file and add new entries to the `keywords` list following this structure.\n\n## Using Theme Components\n\n### Shortcodes\n\nThe theme includes various shortcodes for common components:\n\n```markdown\n{{\u003c products-with-image-grid\n  background=\"bg-gray-50\"\n  product=\"{ title: 'Product Title', ... }\" \u003e}}\n\n{{\u003c features-with-split-image\n  background=\"bg-white\"\n  heading=\"Feature Section Heading\"\n  description=\"Feature section description text\" \u003e}}\n```\n\n### Partials\n\nYou can include partials in your templates:\n\n```go\n{{ partial \"layout/headers/centered_with_eyebrow.html\" (dict\n  \"eyebrow\" \"Eyebrow Text\"\n  \"heading\" \"Main Heading\"\n  \"description\" \"Description text\") }}\n```\n\n## Schema.org Structured Data (SEO)\n\nThe theme includes a comprehensive schema.org structured data implementation to improve SEO and search engine visibility. All schemas are automatically integrated and work out-of-the-box.\n\n### What's Included\n\nThe theme provides **20+ schema.org types** specifically optimized for SaaS businesses:\n\n#### Core Schemas (Automatic)\n- **WebSite** - Site identity with search box functionality\n- **Organization** - Company identity and contact information\n- **WebPage** - Auto-detecting page types (AboutPage, ContactPage, FAQPage, etc.)\n- **SoftwareApplication** - Product/software description\n\n#### Content Schemas (Auto-detected by section)\n- **Article/BlogPosting** - Blog posts and news articles\n- **Course** - Academy and educational content\n- **Service** - SaaS service offerings\n- **Event** - Webinars and online events\n- **JobPosting** - Career and job listings\n\n#### Enhancement Schemas (Triggered by frontmatter)\n- **Product** - Product listings and pricing\n- **Offer** - Special promotions and deals\n- **ItemList** - Feature lists, integration directories\n- **HowTo** - Step-by-step guides\n- **VideoObject** - Video content\n- **FAQPage** - FAQ sections\n- **QAPage** - Community Q\u0026A\n- **Review/AggregateRating** - Customer testimonials and ratings\n- **Breadcrumbs** - Navigation breadcrumbs\n- **Author/Person** - Content authors\n\n### How It Works\n\nSchema.org structured data is **automatically integrated** via the `schemas.html` partial which is included in the theme's `head.html`.\n\n**Core schemas** (WebSite, Organization, WebPage) are always included on every page.\n\n**Content-specific schemas** are triggered by **frontmatter parameters** - not by hardcoded section names. This makes the system work with any Hugo project structure.\n\nAdd parameters to your page frontmatter to enable specific schemas:\n```yaml\n---\ntitle: \"My Page\"\nschemaType: \"Article\"       # Triggers Article schema\nauthor: \"authorkey\"         # Triggers Author schema\nfaq: [...]                  # Triggers FAQ schema\nproduct: {...}              # Triggers Product schema\n---\n```\n\n### Configuration\n\n#### Site-Level Configuration\n\nAdd to your `config/_default/params.toml` or `hugo.toml`:\n\n```toml\n[params]\n  # Enable site search box in Google\n  searchUrl = \"/search/\"\n\n  [params.organization]\n    name = \"Your Company Name\"\n    legalName = \"Your Company Legal Name Inc.\"\n    description = \"Company description\"\n    logo = \"/images/logo.png\"\n    email = \"contact@example.com\"\n    telephone = \"+1-555-555-5555\"\n    foundingDate = \"2010-01-01\"\n\n    [params.organization.address]\n      streetAddress = \"123 Main St\"\n      addressLocality = \"City\"\n      addressRegion = \"State\"\n      postalCode = \"12345\"\n      addressCountry = \"US\"\n\n    [[params.organization.sameAs]]\n      \"https://facebook.com/yourcompany\"\n    [[params.organization.sameAs]]\n      \"https://twitter.com/yourcompany\"\n    [[params.organization.sameAs]]\n      \"https://linkedin.com/company/yourcompany\"\n\n  [params.software]\n    name = \"Your Software Name\"\n    description = \"Your software description\"\n    applicationCategory = \"BusinessApplication\"\n    operatingSystem = \"Windows, macOS, Linux, Web\"\n    softwareVersion = \"1.0.0\"\n    screenshot = \"/images/screenshot.png\"\n\n    [params.software.offers]\n      price = \"99.00\"\n      priceCurrency = \"USD\"\n\n    [params.software.aggregateRating]\n      ratingValue = \"4.8\"\n      reviewCount = \"250\"\n      bestRating = \"5\"\n```\n\n#### Page-Level Configuration\n\nAdd schema data to your page frontmatter. Use the `schemaType` parameter to specify the main content type:\n\n**Blog Posts/Articles:**\n```yaml\n---\ntitle: \"Article Title\"\ndescription: \"Article description\"\nschemaType: \"Article\"          # or \"BlogPosting\", \"TechArticle\", \"NewsArticle\"\ndate: 2026-01-20\nauthor: \"authorkey\"            # References data/authors.yaml\nimage: \"/images/article.jpg\"\ntags: [\"tag1\", \"tag2\"]\n---\n```\n\n**Course/Academy Pages:**\n```yaml\n---\ntitle: \"Course Title\"\ncourseMode: \"online\"\neducationalLevel: \"Beginner\"\ntimeRequired: \"PT4H\"\n---\n```\n\n**Event/Webinar Pages:**\n```yaml\n---\ntitle: \"Webinar Title\"\nevent:\n  name: \"SaaS Marketing Webinar\"\n  description: \"Learn how to grow your SaaS\"\n  startDate: \"2026-02-15T14:00:00-05:00\"\n  endDate: \"2026-02-15T15:00:00-05:00\"\n  eventAttendanceMode: \"OnlineEventAttendanceMode\"\n  location: \"https://yoursite.com/webinar\"\n  offers:\n    price: \"0\"\n    priceCurrency: \"USD\"\n---\n```\n\n**FAQ Sections:**\n```yaml\n---\ntitle: \"FAQ\"\nfaq:\n  - question: \"How does it work?\"\n    answer: \"It works by...\"\n  - question: \"What is the price?\"\n    answer: \"The price is...\"\n---\n```\n\n**Product Pages:**\n```yaml\n---\ntitle: \"Product Name\"\nproduct:\n  name: \"Product Name\"\n  description: \"Product description\"\n  sku: \"PROD-001\"\n  offers:\n    price: \"99.00\"\n    priceCurrency: \"USD\"\n---\n```\n\n**Special Offers:**\n```yaml\n---\ntitle: \"Special Offer\"\noffer:\n  name: \"50% Off Annual Plan\"\n  price: \"499\"\n  priceCurrency: \"USD\"\n  priceValidUntil: \"2026-12-31\"\n---\n```\n\n### Using Schemas in Custom Layouts\n\nWhile schemas are automatically included via `head.html`, you can manually include specific schemas in custom layout files:\n\n**Include a specific schema:**\n```go\n{{/* Single service */}}\n{{ partial \"schemaorg/service.html\" (dict \"service\" .Params.service) }}\n\n{{/* Multiple products */}}\n{{ partial \"schemaorg/product.html\" (dict \"products\" .Params.products) }}\n\n{{/* Event with custom data */}}\n{{ partial \"schemaorg/event.html\" (dict\n  \"name\" \"Event Name\"\n  \"description\" \"Event description\"\n  \"startDate\" \"2026-02-15T14:00:00-05:00\"\n) }}\n```\n\n**Available schema partials:**\nAll schema partials are located in `themes/boilerplate/layouts/partials/schemaorg/`:\n- `article.html` - Blog posts and articles\n- `aggregaterating.html` - Ratings and reviews\n- `author.html` - Content authors\n- `breadcrumbs.html` - Navigation breadcrumbs\n- `course.html` - Educational content\n- `discussion.html` - Forum discussions\n- `event.html` - Events and webinars\n- `faq.html` - FAQ pages\n- `howto.html` - Step-by-step guides\n- `itemlist.html` - Lists of items\n- `jobposting.html` - Job listings\n- `offer.html` - Special offers\n- `organization.html` - Company information\n- `product.html` - Products\n- `qapage.html` - Q\u0026A pages\n- `reviews.html` - Customer reviews\n- `service.html` - Service offerings\n- `softwareapplication.html` - Software products\n- `video.html` - Video content\n- `webpage.html` - Web pages\n- `website.html` - Website identity\n\n### Frontmatter Parameters Reference\n\nThe system uses frontmatter parameters to trigger schemas - no hardcoded section names:\n\n| Parameter | Schema Type | Example |\n|-----------|-------------|---------|\n| `schemaType: \"Article\"` | Article/BlogPosting | Blog posts, news |\n| `schemaType: \"TechArticle\"` | TechArticle | Technical guides |\n| `author: \"authorkey\"` | Person/Author | Any content with author |\n| `faq: [...]` | FAQPage | FAQ sections |\n| `product: {...}` | Product | Product pages |\n| `service: {...}` | Service | Service offerings |\n| `event: {...}` | Event | Events, webinars |\n| `courseMode: \"online\"` | Course | Educational content |\n| `video: {...}` | VideoObject | Video content |\n| `howto: {...}` | HowTo | Step-by-step guides |\n| `jobPosting: {...}` | JobPosting | Job listings |\n| `offer: {...}` | Offer | Special promotions |\n| `testimonials: [...]` | Review | Customer reviews |\n| `itemList: [...]` | ItemList | Lists of items |\n\n**Note:** Individual page templates can also explicitly include schemas when needed.\n\n### Testing Your Schemas\n\nValidate your structured data using:\n\n1. **Google Rich Results Test**: https://search.google.com/test/rich-results\n2. **Schema.org Validator**: https://validator.schema.org/\n3. **Google Search Console**: Monitor rich results performance\n\n### Complete Documentation\n\nFor detailed documentation including all available parameters, examples, and configuration options, see:\n`themes/boilerplate/layouts/partials/schemaorg/README.md`\n\n### Benefits\n\nProper schema.org implementation provides:\n- **Better SEO**: Improved search engine understanding of your content\n- **Rich Results**: Enhanced search results with ratings, prices, events, etc.\n- **Knowledge Graph**: Potential inclusion in Google Knowledge Graph\n- **Voice Search**: Better optimization for voice assistants\n- **AI Discoverability**: Improved visibility in AI-driven search (ChatGPT, Perplexity, etc.)\n\n## Customization\n\n### Tailwind Configuration\n\nThe theme uses Tailwind CSS. You can customize the Tailwind configuration by editing the `tailwind.config.js` file in the theme directory.\n\n### CSS Customization\n\nAdd custom CSS by creating a file at `assets/css/custom.css` in your project root.\n\n### Layout Customization\n\nOverride any theme layout by creating a matching file structure in your project's `layouts` directory.\n\n## Troubleshooting\n\n### HUGO Speed\n\nTo start server with debug log:\n\n```bash\nhugo server --gc --templateMetrics --templateMetricsHints  --logLevel debug\n```\n\n### Future date\nDont forget future date is not built by default, if you want to build future posts, you need to add `--buildFuture` flag:\n\n```bash\nhugo server --buildFuture\n```\n\n\n### Printing DEBUG messages during development\nTo print debug messages during development, you can use the `{{ printf }}` function in your templates:\n\n```go\n{{ warnf \"DEBUG get-language-url: jsonify langData: %s\" (jsonify $langData) }}\n```\n\n\n## Project Initialization\n\n### Quick Start\n\n```bash\n# 1. Checkout from git\ngit clone your-repo-url\ncd your-project\n\n# 2. Initialize git submodules\ngit submodule update --init --recursive\n\n# 3. Install dependencies\nnpm install\n\n# 4. Build assets\nnpm run build\n\n# 5. Start development server\nnpm run dev\n```\n\n### Development Workflow\n\n#### Development Mode (with live reload)\n```bash\n# Start development server with watch mode (all languages)\nnpm run dev\n\n# Or with specific options\ngulp dev --en           # English only (faster)\ngulp dev --metrics      # Show template metrics\n```\n\n#### Production Build\n```bash\n# Build assets for production\nnpm run build\n\n# Start server without watch\nnpm start\n```\n\n#### Asset-only Operations\n```bash\n# Build CSS only\ngulp css\n\n# Build JavaScript only\ngulp js\n\n# Watch for changes without server\nnpm run watch\n```\n\n### Gulp Tasks Available\n\n- `gulp` (default) - Build assets and start Hugo server\n- `gulp dev` - Development mode with watch and live reload\n- `gulp css` - Build CSS with Tailwind processing\n- `gulp js` - Bundle JavaScript with ESBuild\n- `gulp watch` - Watch mode for asset changes only\n\n### Server Options\n\nThe Gulp configuration supports various Hugo server options:\n\n- `--en` - English only (faster startup, less memory usage)\n- `--metrics` - Show template metrics and hints\n- Default - All languages (complete multilingual experience)\n\n\n## Generating new content using FlowHunt Flows\n1. copy csv file with columns: flow_input, filename to e.g. scripts directory in theme\n2. go to scripts directory `cd themes/boilerplate/scripts`\n3. activate python environment:\n```bash\nsource .venv/bin/activate\n```\n3. run the script to generate content:\n```bash\npython generate_content.py --input_file mcp_servers_smart_filtered.csv --flow_id 53849f45-6749-42cd-a27c-29562a25998f --output_dir ../../../content/en/mcp-servers \n```\nIMPORTANT: you need in .env file a FlowHunt API key set as `FLOWHUNT_API_KEY=your_api_key_here`, API key needs to be from same workspace as the flow you are using to generate content.\n\n\n### Common Issues\n\n1. **PostCSS Processing Errors**: Ensure you have the correct PostCSS configuration in your project root.\n\n2. **Image Processing Issues**: Check that Hugo has the required permissions to process images.\n\n3. **Multilingual Configuration**: Verify that your content directories match the configured language directories.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nSee [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualityunit%2Fhugo-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqualityunit%2Fhugo-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualityunit%2Fhugo-boilerplate/lists"}