---
name: deploy-markdown-digest-to-github-pages
description: Deploy a markdown digest (e.g., geopolitical news) as a beautiful GitHub Pages site using a Bootstrap blog template, handling DNS CNAME setup, GitHub Pages configuration, and automatic updates.
category: productivity
version: 1.0.0
author: Hermes Agent
---

# Deploy Markdown Digest to GitHub Pages

This skill automates the process of turning a markdown digest file into a polished news site hosted on GitHub Pages with a custom domain, using a Bootstrap-based blog template.

## When to Use

Use this skill when you have a regularly updated markdown file (e.g., a news digest) and want to publish it as a nice-looking website with minimal manual effort, including DNS configuration, GitHub Pages setup, and automatic updates via cron.

## Steps

### 1. Prepare the Markdown Digest
Ensure you have a markdown file at a known path (e.g., `~/geopolitics-digest.md`) that contains the content you wish to publish. The file should be updated regularly by another process (e.g., an RSS gatherer skill).

### 2. Set Up the GitHub Repository
- Create a repository (if not existing) that will host the site, e.g., `username/sitename`.
- Ensure the repository has a `CNAME` file containing your custom domain (e.g., `news.example.com`).
- The repository should be configured to publish from a branch (usually `master` or `main`) and the `/ (root)` folder.

### 3. Configure DNS for the Custom Domain
In your DNS provider (e.g., GoDaddy):
- **Delete any conflicting A records** for the subdomain (e.g., `@` or `www`).
- **Add a CNAME record**:
  - **Host:** your subdomain (e.g., `valentinnews`)
  - **Points to:** `<username>.github.io.` (note the trailing dot)
  - **TTL:** 1 Hour (or lower for faster propagation)
- Wait for DNS propagation (usually a few minutes, up to an hour).

### 4. Enable GitHub Pages and HTTPS
In the repository settings:
- Go to **Settings → Pages**.
- Under **Source**, select the branch (e.g., `master`) and `/ (root)`.
- Save; GitHub will confirm your site is published at `https://<custom-domain>`.
- Ensure **Enforce HTTPS** is checked (may take a few minutes to activate after DNS is correct).

### 5. Convert Markdown to HTML with a Bootstrap Template
The skill provides a script that:
- Reads the markdown digest.
- Converts it to HTML using Python's `markdown` library (with `extra` and `toc` extensions).
- Embeds the HTML into a Bootstrap blog template (similar to Bootstrap's official blog example).
- Includes links to Bootstrap CSS via CDN, optional Google Fonts (Playfair Display), and custom styling for a clean news layout.
- Outputs `index.html` in the repository root.

### 6. Commit and Push Changes
- Add `index.html` (and ensure `CNAME` is present).
- Commit with a descriptive message (e.g., `Update digest YYYY-MM-DD HH:MM`).
- **Before pushing**, run `git pull --rebase origin <branch>` to integrate any remote changes and avoid divergent branch errors.
- Push to the remote.

### 7. Automate with Cron (Optional)
Set up a cron job to run the above steps periodically (e.g., every 3 days at 07:30 UTC). The job should:
- Run the markdown-to-HTML conversion script.
- Commit and push as described.
- Optionally, trigger a site rebuild (GitHub Pages rebuilds automatically on push).

## Template Details

The generated HTML uses:
- **Bootstrap 5.3.3** from CDN (`https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css`).
- **Optional Google Font**: Playfair Display for headings.
- **Included blog.css** from Bootstrap's official blog example (fetched at runtime) for additional styling.
- **Custom CSS** for layout tweaks (padding, header styling, etc.).
- **Responsive layout**: main column for content, sidebar for sources or metadata.
- **Footer** with the reading principle: "Принцип чтения: для каждой темы минимум 2 источника с разных сторон."

## Troubleshooting

- **DNS shows "Not Configured" in GitHub Pages**: Double-check that DNS CNAME is correct and that there are no conflicting A records for the same host.
- **HTTPS not available**: Ensure Enforce HTTPS is checked after DNS propagation; may take up to 10 minutes.
- **Push rejected due to divergent branches**: Always run `git pull --rebase` before pushing.
- **Site shows 404**: Verify the repository is set to publish from the correct branch and folder, and that `index.html` exists at the root.
- **Template looks broken**: Ensure Bootstrap CSS loads (check network console) and that no ad blockers are blocking CDN.

## Example Cron Job

To run every 3 days at 07:30 UTC and update the site:

```bash
cronjob create --name "news-digest-deploy" \
  --prompt "Run the deploy-markdown-digest-to-github-pages skill to update the site." \
  --schedule "30 7 */3 * *" \
  --skills deploy-markdown-digest-to-github-pages \
  --deliver telegram
```

## Notes

- This skill assumes you have write access to the repository and can push using a personal access token (PAT) configured in the environment.
- The markdown digest should be free of raw HTML that could break the template; if needed, sanitize or adjust the conversion.
- The skill is designed for reuse with any markdown digest; simply change the input file path and repository details.

---