DEV Community: px4n

New Projects Page and Open Source

px4n — Thu, 24 Jul 2025 07:34:41 +0000

Added a projects page to the site and open sourced two utilities. It's been a while since I've open
sourced anything, so I started with tools that solve my current daily annoyances:

Bootscope - A kubectl plugin that analyzes pod startup times.

Instead of manually calculating timestamps from kubectl describe, it shows where time is spent during pod initialization and provides actionable recommendations for common bottlenecks like slow image pulls.

Hugo Syndicate - Automatically syndicates Hugo blog posts to platforms like dev.to and Qiita.
This was my first time publishing to npm, so learning about the packaging was cool.

The tool handles canonical URLs, transforms Hugo shortcodes, and uses Git to sync only changed content.

Both are alpha software but functional for daily use.

The projects page will track my open source work and technical projects going forward.

If you use either tool and run into issues, feel free to open an issue on GitHub.

Planning to maintain and improve these and add more tools as I identify repetitive tasks worth automating.

サイトをリニューアルしてHugoに移行

px4n — Sun, 20 Jul 2025 10:44:24 +0000

長年個人サイトを放置してて、昔のブログ記事もあちこちのサービスに散らばってたので、全部ここに集めることにしました。

いろんな静的サイトジェネレーターを転々とした末、HugoとNightfallテーマをカスタマイズして使うことに落ち着きました。革新的なことは何もしてないけど、ちょっとした遊び心と個人的なタッチを加えてみました。

追加した楽しい機能

コナミコマンドのイースターエッグ

どのページでも ↑↑↓↓←→←→BA を押してみてください（めんどくさい人はCtrl+Shift+TでもOK）。レトロなターミナルモードが起動しますよ〜：

マトリックス風の緑文字に黒背景（グロー効果付き）
CRTスキャンライン効果で懐かしい感じに
ページタイトルをタイプライター風に表示
トースト通知でメッセージ表示
開発者ツールを開くとコンソールにASCIIアート

実装はJavaScriptでステートマシンを作ってretro-modeクラスをトグルしてるだけ。レトロモードのスタイルは専用のSCSSファイルに分離して、スキャンラインとグロー効果はCSSアニメーションで実現してます。

カスタム404ページ

404ページをターミナル風にしてみました：

アクセスしようとしたパスをlsコマンド風に表示
whoamiで「lost_user」を返すとか小ネタ満載
「システム診断」セクションでエラー分析っぽく
エラーテキストにグリッチ効果
ナビゲーションボタンで迷子救済

ページソースにASCIIアート

ソース表示するとASCIIアートとビルド情報が見えます。

Hugoのparamsでカスタムアートも設定可能。

コメントにイースターエッグも仕込んでます。地味に気に入ってる機能。

言語切り替えスイッチ（国旗付き）

ちゃんとした言語切り替えを実装：

国旗アイコン使用（絵文字じゃなくてSVGで統一感）
言語切り替えても同じページを維持
アクティブな言語をハイライト
Hugoのi18nシステムと連携

flag-iconsの美しいSVG国旗に感謝！

シリーズナビゲーション

連載記事用のナビゲーションパーシャル追加：

同じシリーズの全記事を表示
現在の記事には「(current)」ラベル
テーマカラーでスタイリング

ターミナル風アニメーション

ホームページの挨拶に点滅カーソル効果、ナビゲーションにアクティブページインジケーター。小さな演出だけど雰囲気出るよね。

タイポグラフィシステム改造

テーマのデフォルトじゃ物足りなかったので：

Source Sans 3で可変フォントウェイト（200-900）
言語別フォントスタック（フォールバック付き）
グローバルフォントスムージング
h2/h3にビジュアルマーカー追加

技術的なメモ

CSPヘッダーがイマイチ

コメントシステム動かすためにContent Security Policyが適当になってる：

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self' 'unsafe-inline' https://cusdis.com"
/>

'unsafe-inline'使ってるのセキュリティ的にアレだよね。そのうち直さないと。

ちょっと便利だったパターン

ナビゲーションのアクティブ状態、多言語パスのせいでJavaScriptが必要になった。まあ現在のURLチェックしてクラス追加するだけの簡単なやつ。

日本語フォントスタックの使い回しにCSSカスタムプロパティが便利：

[lang="ja"] {
  --ja-font-stack: "M PLUS Rounded 1c", "M PLUS 1p", "Noto Sans JP", sans-serif;

  header,
  nav,
  h1,
  h2,
  h3,
  h4,
  h5,
  h6 {
    font-family: var(--ja-font-stack) !important;
  }
}

HugoのSCSSコンパイルは何も設定いらなくて楽。webpackとか要らないの最高。

日本語コンテンツでわかったこと：

removePathAccentsはラテン文字のみ対応
CJK URLには明示的なslugが必要
フォントごとにline-height調整が必要
日本語のウェイト300は英語と全然違って見える

投稿ナビゲーションの配置には:has()セレクタが便利だった。JavaScript要らずで済む。

セットアップ

よくあるCI/CDパイプライン：

GitHub - ソース管理（ブランチ保護ルール付き）
GitHub Actions - PR時にHugoビルドとチェック
Netlify - チェック通ったらmainブランチからデプロイ

こうしておけば変なのがデプロイされることもないし安心。

今後の予定

ちょっとした改善くらい：

もっとイースターエッグ仕込む（作るの楽しいし）
ダーク/ライトモード切り替え
CSPヘッダーちゃんと直す
WebGL実験とかやってみたい

テーマの改造はオープンソースなので、使いたい人はどうぞ。それじゃ！

ちなみにオタクっぽくするため日本語翻訳をAIに頼りました

Automating dev.to Publishing with GitHub Actions

px4n — Thu, 03 Jul 2025 22:51:47 +0000

As someone who has been blogging on my personal Hugo site for years, I recently decided to start sharing my content on dev.to to reach a broader developer audience. However, I quickly realized that manually cross-posting content would be a tedious process. After publishing a technical article on my blog, I'd have to copy, paste, reformat, and manually sync it to dev.to. Not only would this be time-consuming, but it would also be error-prone and likely lead to inconsistencies between platforms.

Since this is actually my first post on dev.to, I thought it would be fitting to share how I automated the entire syndication process using GitHub Actions and Node.js (though I should mention upfront that Node.js isn't my strongest language, so I'd welcome any feedback or suggestions for improvement!).

The Challenge

The main challenges:

Hugo uses shortcodes like {\{< image >\}} and {\{< code >\}} for enhanced functionality
dev.to uses its own liquid tags and doesn't understand Hugo shortcodes
Both platforms handle metadata differently
Keeping canonical URLs consistent required careful URL generation logic
Managing orphaned articles when content gets deleted or renamed

I needed a solution that would:

Automatically detect when blog posts change
Transform Hugo-specific content to dev.to-compatible format
Handle both creating new articles and updating existing ones
Clean up orphaned articles that no longer exist in the source
Provide comprehensive logging and error handling

The Solution: A Simple Sync Script

I built a Node.js script that integrates with GitHub Actions. While Node.js isn't my go-to language, it seemed like the natural choice for this task given the excellent ecosystem around markdown parsing and HTTP APIs. Here's how it works:

Content Detection

The script uses two modes:

Incremental sync: Only processes files changed in the latest commit (perfect for automatic deployments)
Full sync: Processes all markdown files and cleans up orphaned content (great for manual maintenance)

async function getChangedFiles() {
  if (process.env.FORCE_SYNC_ALL === "true") {
    // Process all markdown files in configurable content directory
    const contentDir = process.env.CONTENT_DIR || "content/";
    return findAllMarkdownFiles(contentDir);
  }

  // Only process changed files in content directory
  const contentDir = process.env.CONTENT_DIR || "content/";
  const gitOutput = execSync("git diff --name-only HEAD~1 HEAD", { encoding: "utf8" });
  return gitOutput.split("\n").filter(file => file.startsWith(contentDir) && file.endsWith(".md"));
}

Content Filtering

Not every blog post should go to dev.to. The script includes filtering logic with automatic tag sanitization for dev.to's strict requirements:

function shouldSyncPost(frontMatter, filePath) {
  // Must explicitly opt-in with devto = true
  if (frontMatter.devto !== true) {
    return { sync: false, reason: "dev.to sync not enabled" };
  }

  // Skip drafts and private posts
  if (frontMatter.draft === true || frontMatter.visibility === "private") {
    return { sync: false, reason: "post not ready for publication" };
  }

  // Check directory path (configurable via CONTENT_DIR and allowedDirectories)
  const contentDir = process.env.CONTENT_DIR || "content/";
  const relativePath = filePath.replace(new RegExp(`^${contentDir}`), "");
  const allowedDirs = ["blog/", "articles/", "posts/"];

  if (!allowedDirs.some(dir => relativePath.startsWith(dir))) {
    return { sync: false, reason: "not in allowed directory" };
  }

  // dev.to has a maximum of 4 tags - warn if limiting
  if (frontMatter.tags && frontMatter.tags.length > 4) {
    console.warn(`Post has ${frontMatter.tags.length} tags, limiting to first 4 for dev.to`);
  }

  // No additional filtering needed - devto=true flag is sufficient
  return { sync: true, reason: "all validation checks passed" };
}

Hugo Shortcode Transformation

One of the trickiest parts was converting Hugo shortcodes to dev.to-compatible format:

function transformHugoShortcodes(content) {
  let transformed = content;

  // Transform {\{< image >\}} to markdown
  transformed = transformed.replace(/\{\{<\s*image\s+src="([^"]+)"\s+alt="([^"]*)"\s*.*>\}\}/g, (match, src, alt) => {
    const imageUrl = src.startsWith("/") ? `${process.env.HUGO_BASE_URL}${src}` : src;
    return `![${alt}](${imageUrl})`;
  });

  // Transform {\{< youtube >\}} to dev.to liquid tags
  transformed = transformed.replace(
    /\{\{<\s*youtube\s+([^>\s]+)\s*>\}\}/g,
    (match, videoId) => `{% youtube ${videoId} %}`
  );

  return transformed;
}

Canonical URL Generation

To maintain SEO consistency, the script automatically generates canonical URLs based on Hugo's routing conventions:

function generateCanonicalUrl(filePath, frontMatter) {
  const baseUrl = process.env.HUGO_BASE_URL;

  // Extract relative path from configurable content directory
  const contentDir = process.env.CONTENT_DIR || "content/";
  const relativePath = filePath.replace(new RegExp(`^${contentDir}`), "");

  const fileInfo = path.parse(relativePath);
  const fileName = fileInfo.name;
  const dir = fileInfo.dir;

  // Handle multilingual files (e.g., my-post.en.md)
  const langMatch = fileName.match(/^(.+)\.([a-z]{2})$/);

  let slug, language;
  if (langMatch) {
    slug = langMatch[1];
    language = langMatch[2];
  } else {
    slug = fileName;
    language = null; // Default language (English)
  }

  // Build URL path based on actual file structure
  let urlPath;
  if (language && language !== "en") {
    urlPath = dir ? `/${language}/${dir}/${slug}/` : `/${language}/${slug}/`;
  } else {
    urlPath = dir ? `/${dir}/${slug}/` : `/${slug}/`;
  }

  return `${baseUrl}${urlPath}`;
}

Orphaned Article Cleanup

When I delete or rename blog posts, the corresponding dev.to articles become orphaned. The script handles this automatically:

async function cleanupOrphanedArticles(allHugoFiles, allDevToArticles) {
  const hugoArticles = new Set();

  // Collect all canonical URLs and titles from Hugo files
  for (const file of allHugoFiles) {
    const parsed = parseHugoFile(file);
    if (shouldSyncPost(parsed.attributes, file).sync) {
      hugoArticles.add(parsed.attributes.canonical_url);
      hugoArticles.add(parsed.attributes.title);
    }
  }

  // Find orphaned articles on dev.to
  const orphanedArticles = allDevToArticles.filter(article => {
    const hasCanonicalMatch = hugoArticles.has(article.canonical_url);
    const hasTitleMatch = hugoArticles.has(article.title);
    return !hasCanonicalMatch && !hasTitleMatch;
  });

  // Unpublish orphaned articles
  for (const article of orphanedArticles) {
    if (process.env.AUTO_DELETE_DEVTO === "true") {
      await unpublishArticle(article);
    }
  }
}

GitHub Actions Integration

The script integrates into three different workflows:

1. Automatic Deployment (develop branch)

- name: Sync Hugo Site to dev.to
  run: |
    npm install axios front-matter
    node .github/workflows/scripts/sync-devto.js
  env:
    DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}
    HUGO_BASE_URL: https://yoursite.com
    CONTENT_DIR: content/
    DEBUG_LEVEL: 2
    FORCE_SYNC_ALL: false
    AUTO_DELETE_DEVTO: true

2. Manual Deployment (with optional sync)

- name: Sync Hugo Site to dev.to
  if: github.event.inputs.sync_devto == 'true'
  run: |
    npm install axios front-matter
    node .github/workflows/scripts/sync-devto.js
  env:
    CONTENT_DIR: content/
    DEBUG_LEVEL: 4 # More verbose for manual runs
    FORCE_SYNC_ALL: true

3. Content Validation (CI)

The CI workflow includes validation specifically for dev.to posts:

- name: Validate dev.to Posts
  run: |
    CONTENT_DIR=${CONTENT_DIR:-content/}
    find "$CONTENT_DIR" -name "*.md" | while read post; do
      if grep -q "devto.*=.*true" "$post"; then
        # Check for required fields
        if ! grep -q "title.*=" "$post"; then
          echo "Missing title in $post"
        fi
        if ! grep -q "tags.*=" "$post"; then
          echo "Missing tags in $post"
        fi
        # Check tag count (dev.to maximum is 4)
        tag_count=$(grep -o "tags.*=.*\[.*\]" "$post" | grep -o '"[^"]*"' | wc -l)
        if [ "$tag_count" -gt 4 ]; then
          echo "Warning: $post has $tag_count tags, dev.to allows maximum 4"
        fi
      fi
    done

Real-World Results

Since implementing this system, my content workflow has improved:

No more manual copying: The script handles the content transformation automatically
Consistent formatting: Hugo shortcodes get converted properly
Canonical URLs work: The URL generation logic maintains SEO consistency
Orphaned cleanup: Deleted posts get unpublished from dev.to automatically

So far the system works reliably for my use case. The logging helps when debugging issues, and the validation catches most problems before they reach dev.to.

Configuration Options

The script supports several environment variables for customization:

CONTENT_DIR: Directory containing your markdown files (default: content/)
DEVTO_API_KEY: Your dev.to API key (required)
HUGO_BASE_URL: Base URL for canonical links (required)
FORCE_SYNC_ALL: Process all files vs only changed ones (default: false)
AUTO_DELETE_DEVTO: Auto-cleanup orphaned articles (default: false)
DEBUG_LEVEL: Logging verbosity 0-4 (default: 2)
Tag sanitization: Automatically handles dev.to's alphanumeric-only requirement

Directory Structure Support

The script works with any Hugo content structure:

content/posts/ (traditional)
content/blog/ (common alternative)
content/articles/ (another common pattern)
content/tech/ or any custom directory

Simply set CONTENT_DIR=content/ and configure the allowed subdirectories in the script.

Tag Limitations

dev.to has a maximum of 4 tags per article. The script automatically:

Takes the first 4 tags from your Hugo front matter
Logs a warning when limiting tags
Preserves all tags in your Hugo site

dev.to Tag Restrictions

dev.to has strict tag requirements that the script handles automatically:

Alphanumeric only: Tags can only contain letters and numbers
No special characters: Hyphens, periods, spaces are automatically removed
Maximum length: 30 characters per tag
Maximum count: 4 tags per article

The script automatically sanitizes tags with full transparency:

function sanitizeTagsForDevTo(tags) {
  return tags
    .map(tag => {
      let sanitized = String(tag)
        .toLowerCase()
        .replace(/[^a-z0-9]/g, "") // Remove non-alphanumeric
        .substring(0, 30);

      if (sanitized !== tag.toLowerCase()) {
        console.log(`Tag transformed: "${tag}" → "${sanitized}"`);
      }

      return sanitized;
    })
    .filter(tag => tag.length > 0);
}

Example transformations:

github-actions → githubactions
dev.to → devto
ci-cd → cicd
content-syndication → contentsyndication

This means you can keep your original Hugo tags descriptive and readable - the script handles dev.to compatibility automatically.

Future Improvements

While the current system works great, there are several enhancements I'm considering:

Enhanced Content Transformation

Table conversion: Better handling of Hugo table shortcodes
Math notation: Support for LaTeX math expressions
Interactive elements: Transform Hugo-specific interactive shortcodes

Smarter Sync Logic

Content diffing: Only update articles when content actually changes
Selective field updates: Update only specific fields (tags, title) without republishing
Scheduling: Support for delayed publishing based on Hugo's date fields

Multi-Platform Support

Hashnode integration: Extend to other developer blogging platforms
Medium support: Though their API is more limited

Analytics Integration

Sync tracking: Monitor which posts perform better on which platforms
Engagement metrics: Track cross-platform engagement and adjust strategy accordingly

Better Configuration Management

Environment validation: Better error messages for missing configuration
Config file support: YAML/JSON configuration files as an alternative to environment variables
Directory auto-detection: Automatically detect Hugo content structure

Learning Along the Way

Since Node.js isn't my strongest language, this project was a good learning experience. A few things I discovered:

The front-matter npm package made parsing Hugo's TOML front matter much easier than trying to roll my own parser
Handling async/await properly took some getting used to, especially when processing multiple files in sequence
The regex patterns for shortcode transformation were trickier than expected - there are probably more elegant ways to handle this

Conclusion

If anyone has suggestions for improving the Node.js code, I'd love to hear them.

If you're interested in the implementation details, you can find the complete sync script here: GitHub Repository