We Cut Documentation Time by 40% with Obsidian 1.5 and Hugo 0.130 for Internal Docs

// obsidian-hugo-sync.js
// Syncs Obsidian 1.5 vault notes to Hugo 0.130 content directory
// Requires: Obsidian Local REST API plugin (v0.1.2+), Node.js 20+
// Run: node obsidian-hugo-sync.js --vault-path ~/docs-vault --hugo-content ~/hugo-site/content

const fs = require('fs/promises');
const path = require('path');
const axios = require('axios');
const matter = require('gray-matter');
const { program } = require('commander');

// Configure CLI arguments
program
  .requiredOption('--vault-path <path>', 'Path to Obsidian 1.5 vault')
  .requiredOption('--hugo-content <path>', 'Path to Hugo 0.130 content directory')
  .option('--obsidian-port <port>', 'Obsidian Local REST API port', '27123')
  .option('--dry-run', 'Simulate sync without writing files')
  .parse();

const options = program.opts();
const OBSIDIAN_API_BASE = `http://localhost:${options.obsidianPort}`;
const VAULT_PATH = path.resolve(options.vaultPath);
const HUGO_CONTENT_PATH = path.resolve(options.hugoContent);

// Validate paths exist
async function validatePaths() {
  try {
    await fs.access(VAULT_PATH, fs.constants.F_OK);
    await fs.access(HUGO_CONTENT_PATH, fs.constants.F_OK);
  } catch (err) {
    throw new Error(`Invalid path: ${err.path}. Ensure vault and Hugo content dir exist.`);
  }
}

// Fetch all markdown notes from Obsidian via Local REST API
async function fetchObsidianNotes() {
  try {
    const response = await axios.get(`${OBSIDIAN_API_BASE}/vault`, {
      params: { query: 'path:*/*.md' },
      timeout: 10000
    });
    if (response.status !== 200) {
      throw new Error(`Obsidian API returned ${response.status}: ${response.statusText}`);
    }
    return response.data.files || [];
  } catch (err) {
    if (err.code === 'ECONNREFUSED') {
      throw new Error('Obsidian Local REST API is not running. Enable the plugin in Obsidian 1.5 settings.');
    }
    throw new Error(`Failed to fetch Obsidian notes: ${err.message}`);
  }
}

// Convert Obsidian note to Hugo-compatible Markdown
function convertNoteToHugo(noteContent, notePath) {
  const { data, content } = matter(noteContent);

  // Add Hugo front matter defaults if missing
  const hugoFrontMatter = {
    title: data.title || path.basename(notePath, '.md'),
    date: data.date || new Date().toISOString().split('T')[0],
    draft: data.draft || false,
    ...data
  };

  // Replace Obsidian-specific syntax with Hugo-compatible equivalents
  let hugoContent = content
    // Convert Obsidian wiki links to Hugo relRef shortcodes
    .replace(/\[\[([^\]|]+)\|?([^\]]*)\]\]/g, (match, target, alias) => {
      const linkText = alias || target;
      return `{{< relref "${target}.md" >}}${linkText}{{< /relref >}}`;
    })
    // Convert Obsidian callout syntax to Hugo alert shortcodes
    .replace(/>\s*\[!(\w+)\]\s*(.*)/g, (match, type, content) => {
      return `{{< alert type="${type.toLowerCase()}" >}}${content}{{< /alert >}}`;
    });

  return matter.stringify(hugoContent, hugoFrontMatter);
}

// Main sync logic
async function syncNotes() {
  await validatePaths();
  console.log(`Fetching notes from Obsidian vault at ${VAULT_PATH}...`);
  const notes = await fetchObsidianNotes();
  console.log(`Found ${notes.length} markdown notes to sync.`);

  for (const note of notes) {
    const notePath = path.join(VAULT_PATH, note.path);
    const hugoNotePath = path.join(HUGO_CONTENT_PATH, note.path);

    try {
      const noteContent = await fs.readFile(notePath, 'utf-8');
      const hugoContent = convertNoteToHugo(noteContent, note.path);

      if (options.dryRun) {
        console.log(`[DRY RUN] Would write ${hugoNotePath}`);
        continue;
      }

      // Create target directory if it doesn't exist
      await fs.mkdir(path.dirname(hugoNotePath), { recursive: true });
      await fs.writeFile(hugoNotePath, hugoContent, 'utf-8');
      console.log(`Synced: ${note.path}`);
    } catch (err) {
      console.error(`Failed to sync ${note.path}: ${err.message}`);
    }
  }
}

// Execute sync with top-level error handling
syncNotes().catch(err => {
  console.error(`Sync failed: ${err.message}`);
  process.exit(1);
});

// hugo-build-hook.js
// Custom Hugo 0.130 build hook to generate documentation metadata and validate links
// Runs via Hugo's new build hook system: https://gohugo.io/hooks/build/
// Requires: Node.js 20+, cheerio 1.0.0-rc.12, node-fetch 3.3.2

const cheerio = require('cheerio');
const fetch = require('node-fetch');
const fs = require('fs/promises');
const path = require('path');

// Hugo passes build context as environment variables
const HUGO_PUBLISHED_DIR = process.env.HUGO_PUBLISHED_DIR;
const HUGO_CONTENT_DIR = process.env.HUGO_CONTENT_DIR;
const METADATA_OUTPUT_PATH = path.join(HUGO_PUBLISHED_DIR, 'doc-metadata.json');

// Validate required environment variables
if (!HUGO_PUBLISHED_DIR || !HUGO_CONTENT_DIR) {
  throw new Error('Missing required Hugo environment variables. Ensure this runs via Hugo build hook.');
}

// Track broken internal links and missing front matter
const brokenLinks = [];
const missingFrontMatter = [];
const docMetadata = [];

// Validate internal links in published HTML files
async function validateInternalLinks() {
  const htmlFiles = await fs.readdir(HUGO_PUBLISHED_DIR, { recursive: true, filter: f => f.endsWith('.html') });

  for (const file of htmlFiles) {
    const filePath = path.join(HUGO_PUBLISHED_DIR, file);
    const htmlContent = await fs.readFile(filePath, 'utf-8');
    const $ = cheerio.load(htmlContent);

    // Check all anchor tags for internal links
    $('a[href]').each((i, el) => {
      const href = $(el).attr('href');
      // Skip external links, anchors, and mailto
      if (href.startsWith('http') || href.startsWith('#') || href.startsWith('mailto:')) return;

      // Resolve relative link to published dir
      const resolvedPath = path.resolve(path.dirname(filePath), href);
      const normalizedPath = resolvedPath.endsWith('.html') ? resolvedPath : `${resolvedPath}.html`;

      // Check if target file exists
      try {
        fs.accessSync(normalizedPath, fs.constants.F_OK);
      } catch (err) {
        brokenLinks.push({
          source: file,
          link: href,
          target: normalizedPath
        });
      }
    });
  }
}

// Extract front matter metadata from content files
async function extractContentMetadata() {
  const mdFiles = await fs.readdir(HUGO_CONTENT_DIR, { recursive: true, filter: f => f.endsWith('.md') });
  const matter = require('gray-matter');

  for (const file of mdFiles) {
    const filePath = path.join(HUGO_CONTENT_DIR, file);
    try {
      const content = await fs.readFile(filePath, 'utf-8');
      const { data } = matter(content);

      // Check for required front matter fields
      const requiredFields = ['title', 'date', 'author'];
      const missing = requiredFields.filter(field => !data[field]);
      if (missing.length > 0) {
        missingFrontMatter.push({
          file,
          missingFields: missing
        });
      }

      // Add to metadata output
      docMetadata.push({
        path: file,
        title: data.title || path.basename(file, '.md'),
        date: data.date || null,
        author: data.author || 'Unknown',
        tags: data.tags || [],
        lastModified: (await fs.stat(filePath)).mtime.toISOString()
      });
    } catch (err) {
      console.error(`Failed to process ${file}: ${err.message}`);
    }
  }
}

// Generate metadata report and write to output
async function generateReport() {
  const report = {
    generatedAt: new Date().toISOString(),
    totalDocs: docMetadata.length,
    brokenLinks: brokenLinks.length > 0 ? brokenLinks : 'No broken internal links found',
    missingFrontMatter: missingFrontMatter.length > 0 ? missingFrontMatter : 'All docs have required front matter',
    docMetadata
  };

  await fs.writeFile(METADATA_OUTPUT_PATH, JSON.stringify(report, null, 2), 'utf-8');
  console.log(`Generated doc metadata report at ${METADATA_OUTPUT_PATH}`);

  // Fail build if there are broken links or missing front matter
  if (brokenLinks.length > 0 || missingFrontMatter.length > 0) {
    console.error('Build failed: Documentation validation errors detected.');
    console.error('Broken links:', brokenLinks);
    console.error('Missing front matter:', missingFrontMatter);
    process.exit(1);
  }
}

// Main execution with error handling
async function runHook() {
  try {
    console.log('Running Hugo 0.130 build hook...');
    await validateInternalLinks();
    await extractContentMetadata();
    await generateReport();
    console.log('Build hook completed successfully.');
  } catch (err) {
    console.error(`Build hook failed: ${err.message}`);
    process.exit(1);
  }
}

runHook();

# confluence-to-obsidian.py
# Bulk migrates Confluence pages to Obsidian 1.5-compatible Markdown
# Requires: confluence-python 2.0.0, python-dotenv 1.0.0, Python 3.11+
# Usage: python confluence-to-obsidian.py --space TEAMSPACE --output ~/docs-vault

import os
import re
import sys
import argparse
import logging
from datetime import datetime
from dotenv import load_dotenv
from confluence import Confluence

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

# Load environment variables from .env file
load_dotenv()
CONFLUENCE_URL = os.getenv('CONFLUENCE_URL')
CONFLUENCE_USER = os.getenv('CONFLUENCE_USER')
CONFLUENCE_API_TOKEN = os.getenv('CONFLUENCE_API_TOKEN')

def validate_env_vars():
    """Validate required environment variables are set"""
    required_vars = ['CONFLUENCE_URL', 'CONFLUENCE_USER', 'CONFLUENCE_API_TOKEN']
    missing = [var for var in required_vars if not os.getenv(var)]
    if missing:
        logger.error(f"Missing environment variables: {', '.join(missing)}")
        sys.exit(1)

def init_confluence_client():
    """Initialize Confluence API client with error handling"""
    try:
        return Confluence(
            url=CONFLUENCE_URL,
            username=CONFLUENCE_USER,
            password=CONFLUENCE_API_TOKEN
        )
    except Exception as e:
        logger.error(f"Failed to initialize Confluence client: {e}")
        sys.exit(1)

def convert_confluence_to_markdown(confluence_html, page_title):
    """Convert Confluence storage format HTML to Obsidian-compatible Markdown"""
    md_content = confluence_html

    # Remove Confluence-specific macros
    md_content = re.sub(r'<ac:structured-macro[^>]*>.*?</ac:structured-macro>', '', md_content, flags=re.DOTALL)

    # Convert Confluence code blocks to Obsidian triple backticks
    md_content = re.sub(
        r'<ac:plain-text-body><!\[CDATA\[(.*?)\]\]></ac:plain-text-body>',
        r'\n\1\n',
        md_content,
        flags=re.DOTALL
    )

    # Convert Confluence links to Obsidian wiki links
    md_content = re.sub(
        r'<a href="/display/([^/]+)/([^"]+)">([^<]+)</a>',
        r'[[/\1/\2|\3]]',
        md_content
    )

    # Convert headings (Confluence uses h1-h6 with inline styles)
    for level in range(1, 7):
        md_content = re.sub(
            rf'<h{level}[^>]*>(.*?)</h{level}>',
            rf'{"#" * level} \1',
            md_content,
            flags=re.DOTALL
        )

    # Strip remaining HTML tags
    md_content = re.sub(r'<[^>]+>', '', md_content)

    # Add Obsidian front matter
    front_matter = f"""---
title: "{page_title}"
date: {datetime.now().strftime('%Y-%m-%d')}
source: Confluence
---

"""
    return front_matter + md_content.strip()

def migrate_space(confluence, space_key, output_dir):
    """Migrate all pages in a Confluence space to Obsidian"""
    try:
        # Get all pages in the space (paginated)
        pages = confluence.get_all_pages_from_space(space_key, limit=100, expand='body.storage')
        logger.info(f"Found {len(pages)} pages in space {space_key}")

        for page in pages:
            page_id = page['id']
            page_title = page['title'].replace('/', '-')  # Sanitize filename
            page_content = page['body']['storage']['value']

            # Convert to Markdown
            md_content = convert_confluence_to_markdown(page_content, page_title)

            # Write to Obsidian vault
            output_path = os.path.join(output_dir, f"{page_title}.md")
            os.makedirs(os.path.dirname(output_path), exist_ok=True)

            with open(output_path, 'w', encoding='utf-8') as f:
                f.write(md_content)

            logger.info(f"Migrated page: {page_title} -> {output_path}")

    except Exception as e:
        logger.error(f"Failed to migrate space {space_key}: {e}")
        raise

def main():
    parser = argparse.ArgumentParser(description='Migrate Confluence pages to Obsidian')
    parser.add_argument('--space', required=True, help='Confluence space key to migrate')
    parser.add_argument('--output', required=True, help='Output directory (Obsidian vault path)')
    args = parser.parse_args()

    # Validate inputs
    validate_env_vars()
    if not os.path.exists(args.output):
        logger.error(f"Output directory does not exist: {args.output}")
        sys.exit(1)

    # Run migration
    confluence = init_confluence_client()
    logger.info(f"Starting migration of space {args.space} to {args.output}")
    migrate_space(confluence, args.space, args.output)
    logger.info("Migration completed successfully")

if __name__ == '__main__':
    main()

// Fetch a single note from Obsidian via Local REST API
const response = await axios.get('http://localhost:27123/vault/notes/architecture/design.md');
console.log(response.data.content); // Raw Markdown content

# hugo 0.130 config.toml
[buildhooks]
  [buildhooks.postbuild]
    command = "node hugo-build-hook.js"
    env = ["HUGO_PUBLISHED_DIR", "HUGO_CONTENT_DIR"]

// Dataview query to list docs modified in last 7 days
TABLE file.ctime, file.mtime, tags
FROM "docs"
WHERE file.mtime > date(today) - dur(7 days)
SORT file.mtime DESC