{
  "markdown": "# JetThoughts Website\n\n> Professional software development consultancy website built with Hugo, featuring automated content synchronization from dev.to and comprehensive CI/CD pipeline.\n\n[![Hugo](https://img.shields.io/badge/Hugo-Extended-ff4088.svg)](https://gohugo.io/)\n[![GitHub Pages](https://img.shields.io/badge/Deployed%20on-GitHub%20Pages-blue)](https://jetthoughts.com/)\n[![CI/CD](https://github.com/jetthoughts/jetthoughts.github.io/actions/workflows/publish.yml/badge.svg)](https://github.com/jetthoughts/jetthoughts.github.io/actions)\n\n## 📋 Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Technology Stack](#technology-stack)\n- [Quick Start](#quick-start)\n- [Development](#development)\n- [Testing](#testing)\n- [Deployment](#deployment)\n- [Content Management](#content-management)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n\n## 🌟 Overview\n\nJetThoughts website is a sophisticated static site generator project that showcases the company's software development and consultancy services. The site features automated blog content synchronization from dev.to, a custom Hugo theme, and comprehensive testing framework.\n\n### Key Highlights\n\n- **540+ technical articles** automatically synced from dev.to\n- **Responsive design** with mobile-first approach\n- **Visual regression testing** to ensure consistency\n- **Automated CI/CD** with GitHub Actions\n- **SEO optimized** with proper meta tags and structured data\n- **Performance optimized** with PurgeCSS and asset minification\n\n## ✨ Features\n\n### Content Features\n- **Dynamic blog system** with automated dev.to synchronization\n- **Service showcases** for consultancy offerings\n- **Client case studies** and success stories\n- **Use case demonstrations**\n- **Career opportunities** with Google Forms integration\n- **Contact system** with form submissions\n\n### Technical Features\n- **Static site generation** with Hugo Extended\n- **Automated content sync** every 10 minutes\n- **Visual regression testing** with screenshot comparison\n- **Staging environment** with surge.sh deployment\n- **Multi-level navigation** with dropdown menus\n- **Asset optimization** with PostCSS pipeline\n- **Git-based versioning** for content\n\n## 🛠 Technology Stack\n\n### Core Technologies\n\n| Category | Technologies |\n|----------|-------------|\n| **Static Site Generator** | Hugo Extended (version pinned in `.mise.toml`) |\n| **Theme** | Custom \"Beaver\" theme |\n| **Languages** | HTML, CSS (PostCSS), JavaScript, Ruby |\n| **Package Managers** | Bun (Node.js), Bundler (Ruby) |\n| **Testing** | Minitest, Capybara, Selenium WebDriver |\n| **CI/CD** | GitHub Actions, GitHub Pages |\n| **Content Source** | dev.to API integration |\n\n### Dependencies\n\n#### Bun Dependencies\n```json\n{\n  \"build\": [\"@fullhuman/postcss-purgecss\", \"autoprefixer\", \"cssnano\", \"postcss\"],\n  \"audit\": [\"lighthouse\", \"markdownlint-cli\"],\n  \"deployment\": [\"surge\"]\n}\n```\n\n#### Ruby Dependencies\n```ruby\n# Testing\ngem \"minitest\"\ngem \"capybara\"\ngem \"selenium-webdriver\"\ngem \"snap_diff-capybara\", \"2.0.0.beta4\"\n\n# API & HTTP\ngem \"httparty\"\ngem \"faraday\"\ngem \"sanity-ruby\"\n\n# Development\ngem \"standard\"\ngem \"simplecov\"\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **[mise](https://mise.jdx.dev)** — installs the pinned toolchain (Hugo Extended, Bun, Node, Ruby) from `.mise.toml`\n- **libvips** — screenshot-diff tests (`brew install vips` / `apt-get install libvips42`)\n- **Chrome or Chromium** — system tests (set `CHROME_BIN=/path/to/chrome` if not on PATH)\n- **Git** for version control\n\nExact versions live in `.mise.toml` (mirrored in `.ruby-version`); CI carries\nits own copies of those pins - keep them in sync when bumping. See\n[docs/SETUP.md](docs/SETUP.md) for the full walkthrough.\n\n### Installation\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/jetthoughts/jetthoughts.github.io.git\ncd jetthoughts.github.io\n```\n\n2. **Run the setup script:**\n```bash\nbin/setup\n```\n\nThis installs the pinned toolchain via mise, system libraries via\nBrewfile/apt, JS dependencies via Bun, and Ruby gems via Bundler — then runs\na doctor that verifies each piece and prints a fix for anything missing.\n\n3. **Start the development server:**\n```bash\nbin/dev\n```\n\nVisit `http://localhost:1313` to view the site. (`bin/dev` wraps\n`hugo server` with the PATH and env the PostCSS pipeline needs — a bare\n`hugo server -D` will fail to build CSS.)\n\n## 💻 Development\n\n### Project Structure\n\n```\njetthoughts.github.io/\n├── content/           # Content files (markdown)\n│   ├── blog/         # Blog posts (synced from dev.to)\n│   ├── pages/        # Static pages\n│   ├── clients/      # Client case studies\n│   ├── services/     # Service descriptions\n│   └── use-cases/    # Use case examples\n├── themes/beaver/     # Custom theme\n│   ├── layouts/      # Template files\n│   ├── assets/       # Theme assets\n│   └── archetypes/   # Content templates\n├── assets/           # Site assets (images, etc.)\n├── data/             # Data files (YAML)\n├── static/           # Static files\n├── lib/              # Ruby libraries for sync\n├── test/             # Test suite\n└── bin/              # Utility scripts\n```\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `bin/dev` | Start development server with drafts |\n| `bin/hugo-build` | Build + validate site (course validators, PurgeCSS warm-up) |\n| `bin/test` | Run critical test suite (`bin/rake test:critical`) |\n| `bin/qtest` | Scoped visual gate for a changed CSS file/page (fast, budgeted) |\n| `bin/dtest` | Same suite in Linux/Docker (visual baselines CI-parity) |\n| `bin/dtest-all` | Full suite in Docker, detached (log in `tmp/dtest-all.log`) |\n| `bin/setup-test-env` | Install the pinned Chrome-for-Testing + fonts stack bare-metal |\n| `bin/rake test:screenshots:reset` | Restore overwritten screenshot baselines |\n| `bin/lint-css` | Stylelint warning ratchet |\n| `bin/sync_with_devto` | Sync blog posts from dev.to |\n| `bin/surge/deploy` | Deploy to staging (surge.sh) |\n| `bin/setup` | Initial project setup + doctor |\n\n### Environment Variables\n\nCreate a `.env` file for local development:\n\n```bash\n# API Keys\nDEVTO_API_KEY=your_dev_to_api_key\n\n# Deployment\nSURGE_DOMAIN=your-staging-domain.surge.sh\n\n# Testing (see docs/SETUP.md for the pinned-browser flow)\nCHROME_BIN=...             # optional: explicit Chrome binary for system tests\nCHROMEDRIVER_PATH=...      # optional: matching chromedriver\nALLOW_DIRTY_SCREENSHOTS=1  # bypass the dirty-baseline guard intentionally\n```\n\n## 🧪 Testing\n\nThe project includes comprehensive testing with multiple test types:\n\n### Running Tests\n\n```bash\n# Critical suite (system + visual regression)\nbin/test\n\n# Specific suites\nbin/rake test:unit          # Unit tests (validators, sync, templates)\nbin/rake test:system        # All system tests\nbin/rake test:critical      # Critical pages subset\nbin/dtest                   # Critical suite in Linux/Docker\n\n# Single test file\nbin/test test/system/desktop_site_test.rb\n```\n\n### Test Categories\n\n1. **Unit Tests** - Test individual components and functions\n2. **System Tests** - Full browser automation tests\n3. **Visual Regression** - Screenshot comparison tests\n4. **Integration Tests** - API and external service tests\n\n## 📦 Deployment\n\n### Production Deployment\n\nThe site automatically deploys to GitHub Pages when changes are pushed to the `master` branch:\n\n1. **Push to master:**\n```bash\ngit push origin master\n```\n\n2. **GitHub Actions workflow:**\n   - Builds the site with Hugo\n   - Runs tests\n   - Deploys to GitHub Pages\n\n### Staging Deployment\n\nDeploy to surge.sh for testing:\n\n```bash\nbin/surge/deploy\n```\n\nAccess staging at: `https://your-domain.surge.sh`\n\n## 📝 Content Management\n\n### Blog Posts\n\nBlog posts are automatically synchronized from dev.to:\n\n#### Automatic Sync\n- Runs every 10 minutes via GitHub Actions\n- Syncs posts tagged with \"jetthoughts\" organization\n\n#### Manual Sync\n```bash\nbin/sync_with_devto [options]\n\nOptions:\n  --dry        Preview changes without syncing\n  --force      Force sync all articles\n  --dry --force Preview forced sync\n```\n\n#### Creating New Posts\n\n1. **Write on dev.to:**\n   - Publish under JetThoughts organization\n   - Add relevant tags (first 2 tags used in URL)\n   \n2. **Trigger sync:**\n   - Wait for automatic sync (10 minutes)\n   - Or run manual sync command\n\n#### URL Management\n\nCustom URLs can be configured in `devto_urls_mapping.csv`:\n```csv\narticle_id,custom_url\n12345,/blog/my-custom-url/\n```\n\n### Static Pages\n\nCreate new pages using Hugo archetypes:\n\n```bash\n# Create a new service page\nhugo new services/new-service/index.md\n\n# Create a new client case study\nhugo new clients/new-client/index.md\n\n# Create a new use case\nhugo new use-cases/new-use-case/index.md\n```\n\n### Menu Configuration\n\nEdit `hugo.toml` to modify navigation:\n\n```toml\n[[menu.main]]\n  identifier = \"new-item\"\n  name = \"New Item\"\n  pageRef = \"pages/new-item/\"\n  weight = 70\n```\n\n## 📚 Documentation\n\n### Available Documentation\n\n| Document | Description |\n|----------|-------------|\n| [README.md](README.md) | Project overview and setup |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines |\n| [SETUP.md](docs/SETUP.md) | Detailed setup instructions |\n| [CI-CD](docs/50-59-deployment-operations/50.02-ci-cd-pipeline-analysis-reference.md) | CI/CD pipeline documentation |\n| [DEV-TO-INTEGRATION](docs/80-89-integration-apis/80.01-dev-to-integration-how-to.md) | dev.to sync documentation |\n| [AGENT-GUIDANCE.md](docs/60-69-project-management/60.01-agent-guidance-reference.md) | Agent resource locations and guidelines |\n\n### API Documentation\n\nThe project includes several internal APIs and scripts:\n\n- **Sync API** (`lib/sync/`) - Handles dev.to synchronization\n- **Testing API** (`test/`) - Test utilities and helpers\n- **Build Scripts** (`bin/`) - Automation scripts\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Quick Contribution Steps\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`bin/test`)\n5. Commit changes (`git commit -m 'Add amazing feature'`)\n6. Push to branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## 📄 License\n\nThis work is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/).\n\n## 🙏 Acknowledgments\n\n- Hugo static site generator team\n- dev.to for content platform integration\n- GitHub for hosting and CI/CD\n- All contributors and maintainers\n\n## 📞 Contact\n\n- **Website:** [https://jetthoughts.com](https://jetthoughts.com)\n- **Email:** info@jetthoughts.com\n- **Phone:** +1 754 216 9568\n- **GitHub:** [@jetthoughts](https://github.com/jetthoughts)\n\n---\n\n<p align=\"center\">Made with ❤️ by JetThoughts Team</p>",
  "bytes": 10888,
  "sha": "966c4f490bc59bb3c2e7feb1a0af04cbeeecead97a8d490fffd0764fbe013b53",
  "repo_slug": "jetthoughts/jetthoughts.github.io",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_jetthoughts_jetthoughts_github_io_okf_in_76d16edd/readme"
}