{"id":47095734,"url":"https://github.com/alltuner/blogtuner","last_synced_at":"2026-03-12T14:11:07.964Z","repository":{"id":285018492,"uuid":"950124429","full_name":"alltuner/blogtuner","owner":"alltuner","description":"No excuse, blog every day","archived":false,"fork":false,"pushed_at":"2025-12-05T12:36:13.000Z","size":2396,"stargazers_count":4,"open_issues_count":11,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-03T20:32:46.897Z","etag":null,"topics":["blogging","markdown","markdown-to-html","minimal","rss-generator","static-site-generator"],"latest_commit_sha":null,"homepage":"https://github.com/alltuner/blogtuner","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alltuner.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-17T17:05:49.000Z","updated_at":"2025-12-05T12:36:07.000Z","dependencies_parsed_at":"2025-03-29T00:25:13.550Z","dependency_job_id":"666df266-f08b-439f-9a3d-54c8d4fcafb3","html_url":"https://github.com/alltuner/blogtuner","commit_stats":null,"previous_names":["alltuner/blogtuner"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/alltuner/blogtuner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alltuner%2Fblogtuner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alltuner%2Fblogtuner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alltuner%2Fblogtuner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alltuner%2Fblogtuner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alltuner","download_url":"https://codeload.github.com/alltuner/blogtuner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alltuner%2Fblogtuner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30427887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T14:00:25.264Z","status":"ssl_error","status_checked_at":"2026-03-12T13:59:52.690Z","response_time":114,"last_error":"SSL_read: 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":["blogging","markdown","markdown-to-html","minimal","rss-generator","static-site-generator"],"created_at":"2026-03-12T14:11:03.214Z","updated_at":"2026-03-12T14:11:07.956Z","avatar_url":"https://github.com/alltuner.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlogTuner 📜\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003e Blog every damn day, no excuses.\n\nBlogTuner is a ridiculously simple static blog generator that converts Markdown files to HTML with zero fuss. No complex configurations, no steep learning curves—just write and publish.\n\n## Demo\n\nBlogTuner is being used on [davidpoblador.com/blog](https://davidpoblador.com/blog), if you want to get an idea!\n\n## ✨ Features\n\n- **Dead Simple**: Convert Markdown to HTML—that's it\n- **Lightning Fast** ⚡: Generates your entire site in milliseconds\n- **No Excuses** 🙅: Removes all barriers to daily blogging\n- **RSS Ready** 📡: Automatically generates a feed for your blog\n- **Markdown Power** 📝: Write in Markdown, publish as HTML\n- **Smart Defaults** 🧠: Sensible defaults with minimal configuration\n- **Draft Support** 📋: Mark posts as drafts with frontmatter\n- **Date Flexibility** 📅: Use frontmatter dates or file timestamps\n- **Smart File Organization** 🗃️: Git-aware file renaming to standard format\n- **GitHub Pages Ready** 🚀: Generate static HTML perfect for free hosting\n- **Substack Import** 📥: Import posts from Substack blogs with a single command\n- **Image Support** 🖼️: Automatic image processing, optimization and thumbnails\n- **Pinned Posts** 📌: Pin important posts to the top of your blog\n- **Post Management** 🔧: CLI commands to publish, unpublish, and delete posts\n- **SEO Friendly** 🌐: Generates proper metadata for search engines and social media\n\n## 🤔 Motivation\n\nSome folks such as [Simon Willison](https://simonwillison.net/) have convinced me to start blogging my thoughts. I wanted to keep things simple—just a dumb set of markdown files should be enough to create a super simple HTML blog.\n\nEven with great tools like [Zola](https://www.getzola.org/), [Hugo](https://gohugo.io/), and [Pelican](https://getpelican.com/) available, they felt too complicated for what I needed. I wanted the minimal expression of simplicity. Hence, BlogTuner was born.\n\nThe idea is to keep your markdown files in a repo, generate HTML with BlogTuner, and deploy to a service like GitHub Pages. As simple as that.\n\n## 📦 Installation\n\nThe recommended way to use BlogTuner is via `uvx` (by the way, if you haven't heard about `uv` you should [read about it](https://github.com/astral-sh/uv)):\n\n```bash\nuvx blogtuner build source_dir target_dir\n```\n\nIf you prefer to install it:\n\n```bash\nuv pip install blogtuner\n```\n\nYou can use the traditional `pip` workflow without `uv` as well.\n\n## 🚀 Usage\n\n### Basic Usage\n\n```bash\n# Create a new blog directory\nmkdir myblog\ncd myblog\n\n# Create your first post\necho \"# Hello World\" \u003e first-post.md\n\n# Generate your blog\nuvx blogtuner build . _site\n```\n\n### Post Management\n\nBlogTuner comes with a set of commands to manage your posts:\n\n```bash\n# List all your posts\nblogtuner post list\n\n# Publish a draft post\nblogtuner post publish slug-of-your-post\n\n# Unpublish a post (mark as draft)\nblogtuner post unpublish slug-of-your-post\n\n# Delete a post\nblogtuner post delete slug-of-your-post\n```\n\n### Importing Content\n\n#### From Markdown Files\n\n```bash\n# Import a markdown file as a new post\nblogtuner post import markdown /path/to/your/post.md\n```\n\n#### From Substack\n\n```bash\n# Import all posts from a Substack blog\nblogtuner post import substack https://yourblog.substack.com\n```\n\n### Smart File Organization\n\nBlogTuner automatically renames your files to follow the pattern `YYYY-MM-DD-slug.md`.\n\nWhen BlogTuner normalizes your file names, it intelligently detects if the file is part of a Git repository:\n\n- If the file is tracked in Git, it uses `git mv` to rename it, preserving your Git history\n- If not, it falls back to a regular file system rename\n\nThis makes BlogTuner play nicely with your Git workflow while keeping everything organized.\n\n### Images\n\nBlogTuner automatically processes images for your posts:\n\n1. Place an image with the same name as your post (e.g., `2024-04-05-my-post.jpg` for `2024-04-05-my-post.md`)\n2. BlogTuner will automatically process it, create optimized WebP versions, and generate thumbnails\n3. Images are referenced in your HTML and feed automatically\n\n### Frontmatter\n\nPosts can include TOML frontmatter at the beginning of the file (if you don't include it, it will be generated during the first run):\n\n```markdown\n+++\ntitle = \"My Awesome Post\"\npubdate = \"2024-04-05\"\ndraft = false\nslug = \"custom-slug\"  # Optional, defaults to filename\ntags = [\"tech\", \"programming\"]\npinned = false  # Set to true to pin this post to the top\noneliner = \"A brief description of this post\"\ndescription = \"A longer description for SEO purposes\"\noriginal_href = \"https://original-source.com/post\"  # If republishing from elsewhere\n+++\n\n# My Awesome Post\n\nContent goes here...\n```\n\n### Blog Configuration\n\nCreate a `blog.toml` in your source directory (it will be created on the first run if you're lazy like me):\n\n```toml\nname = \"My Awesome Blog\"\nauthor = \"Your Name\"\nbase_url = \"https://yourdomain.com\"\nbase_path = \"/\"\nlang = \"en\"\ntimezone = \"UTC\"\ndescription = \"A blog about interesting things\"\nfooter_text = \"Powered by \u003ca href='https://github.com/alltuner/blogtuner'\u003eBlogTuner\u003c/a\u003e\"\nlinks = { \"GitHub\" = \"https://github.com/yourusername\", \"Twitter\" = \"https://twitter.com/yourusername\" }\ntwitter_metadata = { \"site\" = \"@yoursite\", \"creator\" = \"@yourusername\" }\n```\n\n## 🛠️ Features in Detail\n\n### Post Processing\n\n- **Automatic Metadata**: Extract frontmatter or use defaults\n- **Date Handling**: Parse dates from frontmatter or use file timestamps\n- **Drafts**: Drafts won't appear in the public index or feed\n- **File Normalization**: Files renamed to YYYY-MM-DD-slug.md with Git awareness\n- **Syntax Highlighting**: Code blocks are automatically highlighted\n- **Format Normalization**: Markdown is normalized to ensure consistent formatting\n\n### Site Generation\n\n- **HTML Generation**: Clean, simple HTML for each post and index\n- **Feed Generation**: RSS feed for syndication\n- **CSS Bundling**: Simple, clean CSS included automatically\n- **Fast Processing**: Efficient even for large numbers of posts\n- **Image Processing**: Automatic optimization and thumbnail generation\n- **SEO Metadata**: Proper metadata for search engines and social media\n\n### LLM-Enhanced Features\n\n- **Substack Import**: Uses LLM-powered conversion from HTML to Markdown\n- **Content Processing**: Intelligent handling of various content types\n\n## 🧑‍💻 Contributing\n\nWant to contribute? Awesome! But read this first:\n\n**I'm looking for simplicity, not complexity.**\n\nThe best contributions to BlogTuner are ones that:\n\n- Make it even simpler to use\n- Remove complexity, not add it\n- Fix bugs or improve performance\n- Enhance the core functionality without bloating it\n\nIf your PR adds a ton of new features or dependencies, it's probably not a good fit.\n\nThe guiding principle is: \"How can we make blogging have even fewer excuses?\"\n\nSubmit your PRs and let's make blogging simpler together!\n\n## 🔄 Example Workflow\n\n1. Write posts in Markdown with optional TOML frontmatter\n2. Run BlogTuner to generate HTML and RSS feed\n3. Push HTML to GitHub Pages or your hosting service\n4. Repeat daily (no excuses!)\n\n## CLI Commands Reference\n\n```\nblogtuner --help                     # Show help for all commands\nblogtuner version                    # Show version\nblogtuner build TARGET_DIR           # Build site to target directory\nblogtuner post list                  # List all posts\nblogtuner post publish SLUG          # Publish a draft post\nblogtuner post unpublish SLUG        # Mark a post as draft\nblogtuner post delete SLUG           # Delete a post\nblogtuner post import markdown FILE  # Import a markdown file\nblogtuner post import substack URL   # Import posts from Substack\n```\n\n## 👨‍💻 Author\n\nBlogTuner is developed by [David Poblador i Garcia](https://davidpoblador.com/) as part of [All Tuner Labs](https://alltuner.com/). It's created by someone who believes blogging should be simple, fast, and without barriers.\n\n## 📄 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falltuner%2Fblogtuner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falltuner%2Fblogtuner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falltuner%2Fblogtuner/lists"}