noblog 0.1.1 → 0.2.0-beta

package/README.md

@@ -1,87 +1,208 @@
-# noblog
+# 📝 Noblog
 
-This package aims to generate static content from notion.so and provide a plugable component/theme market for you bloggers.
+> Transform your Notion content into beautiful static blogs with Astro
 
-the pattern would be like notablog (see reference), but more flexiable thanks to the mighty power of Astro
+[![npm version](https://badge.fury.io/js/noblog.svg)](https://badge.fury.io/js/noblog)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-# Usage
+Noblog generates static content from Notion databases and provides a pluggable component/theme marketplace for bloggers. Inspired by [notablog](https://github.com/dragonman225/notablog) but more flexible thanks to the power of Astro.
 
+## 🆚 Why Noblog vs notion-to-md?
+
+While Noblog uses [notion-to-md](https://github.com/souvikinator/notion-to-md) under the hood, it provides significant improvements for blog generation:
+
+### 🔧 **Enhanced Markdown Generation**
+
+**Problem with notion-to-md:**
+When dealing with complex formatting like nested styles (e.g., `{BLOCK1}` and `{BLOCK2}` both bold, but only `BLOCK1` also italic), notion-to-md generates malformed markdown:
+
+```markdown
+_**BLOCK1**_**BLOCK2** # Broken: unmerged tags
+```
+
+**Noblog's Solution:**
+
+- **Merged Tag Handling**: Properly merges nested formatting tags
+- **Clean Markdown Output**: Generates valid, renderer-friendly markdown
+- **Astro-Optimized**: Specifically designed for static site generation
+
+### 🏗️ **Complete Blog Structure**
+
+**notion-to-md:** Just converts pages to markdown
+
+**Noblog:**
+
+- ✅ Automatic file structure generation
+- ✅ Parent/child page organization
+- ✅ Astro-compatible frontmatter
+- ✅ Customizable save paths
+- ✅ Layout path customization
+- ✅ Theme marketplace ready
+
+### ⚡ **One-Command Solution**
+
+Instead of manually handling notion-to-md output and building your own file structure:
+
+```bash
+# With Noblog - everything handled automatically
+noblog --layout ../../layouts/BlogLayout.astro
+
+# With notion-to-md - you'd need to build everything yourself
 ```
+
+> **Note:** Noblog includes improvements to notion-to-md's core parsing logic, fixing edge cases like unmerged formatting tags that can break markdown renderers.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
 npm install -g noblog
+```
+
+### Basic Usage
+
+```bash
 noblog
 ```
 
-1. \[OPTIONAL\] Duplicate this [database](https://www.notion.so/humbornjo/fa0faae85c504934a4a86cfa70302850?v=2abd1079ae134fbd8df2604765baa1df) and write blogs on it.
+That's it! Noblog will fetch your Notion content and generate static markdown files.
+
+### 🛠️ Command-Line Options
 
-2. Find a astro template, here is a shabby template I made: [nobloger](https://github.com/humbornjo/nobloger)
+Noblog supports various command-line options to customize your blog generation:
 
-3. set two env variables:
+```bash
+# Basic usage with default settings
+noblog
 
-   ```
-   NOBLOG_DATABASE_ID: your notion database id.
-   NOTION_API_SECRET: your notion api secret.
-   ```
+# Custom layout path
+noblog --layout ../../layouts/BlogLayout.astro
 
-4. Run `noblog` and deploy your site.
+# Custom save and sub paths with layout
+noblog ./content/blog/ ./content/blog/subpages/ --layout ../../../layouts/CustomLayout.astro
 
-By default, `noblog` saves all your post (the posts at the surface og your database) under `SAVE_PATH`.
+# Verbose output for debugging
+noblog -v
+# or
+noblog --verbose
+```
 
-The articles that are not directly posted on the database is saved under `SAVE_PATH/SUB_PATH`.
+**Available Options:**
 
-The default value of `SAVE_PATH` is `./src/pages/posts/`, `SUB_PATH` is `nob_children/`
+- `--layout PATH` - Custom layout path relative to the posts directory (default: `../../layouts/MarkdownPostLayout.astro`)
+- `-v, --verbose` - Print more messages for debugging
+- `-h, --help` - Show help message
+- `--version` - Show version information
 
-So if you run `noblog` only, the file structure would be,
+**Positional Arguments:**
 
+- `SAVE_PATH` - Directory to save main posts (default: `./src/pages/posts/`)
+- `SUB_PATH` - Subdirectory for nested content (default: `nob_children/`)
+
+## 📋 Setup Guide
+
+### 1. Create Your Notion Database
+
+Duplicate this [template database](https://www.notion.so/humbornjo/fa0faae85c504934a4a86cfa70302850?v=2abd1079ae134fbd8df2604765baa1df) and start writing your blog posts in Notion.
+
+### 2. Configure Environment Variables
+
+Set up your Notion API credentials:
+
+```bash
+export NOBLOG_DATABASE_ID="your-notion-database-id"
+export NOTION_API_SECRET="your-notion-api-secret"
 ```
-project root
-└──src
-   └── pages
-       └── posts
-           ├── blog_1.md
-           ├── blog_2.md
-           └── nob_children
-               ├── referenced_blog_1.md
-               ├── referenced_blog_2.md
-               ├── referenced_blog_3.md
-               ├── referenced_blog_4.md
-               └── referenced_blog_5.md
-```
 
-Save dir could be altered by add args when running command,
+### 3. Choose a Template
+
+Pick an Astro template that supports Noblog. Here's a starter template: **[nobloger](https://github.com/humbornjo/nobloger)**
+
+### 4. Deploy Your Site
+
+Run `noblog` to generate your content, then deploy your Astro site to your preferred hosting platform.
+
+## 📁 File Structure
+
+By default, Noblog organizes your content like this:
 
 ```
-noblog <SAVE_PATH> <SUB_PATH>
+project-root/
+└── src/
+    └── pages/
+        └── posts/
+            ├── blog-post-1.md          # Direct database entries
+            ├── blog-post-2.md
+            └── nob_children/
+                ├── sub-post-1.md       # Referenced/child pages
+                ├── sub-post-2.md
+                └── sub-post-3.md
 ```
 
-At this time, all the generated markdown is with Astro style, which means each file has a frontmatter like this,
+### Custom Save Paths
+
+You can customize the output directories:
 
+```bash
+noblog <SAVE_PATH> <SUB_PATH>
+
+# Example:
+noblog ./content/blog/ ./content/blog/subpages/
 ```
+
+## 🎯 Markdown Output
+
+Generated markdown files include Astro-compatible frontmatter:
+
+```markdown
 ---
 layout: ../../layouts/MarkdownPostLayout.astro
-title: "golang blog"
-tags: ["lang", "go"]
+title: "Your Blog Post Title"
+tags: ["tag1", "tag2", "tag3"]
 pubDate: 2024-01-24
 archived: false
-description: "sometimes I hate, sometimes I love. <3"
+description: "Your post description here"
 ---
+
+# Your content starts here...
 ```
 
-Layout used is hard coded in the name of `./src/layouts/MarkdownPostLayout.astro`
+## 🔧 Requirements
+
+**Any Astro template can be used with Noblog!** The only requirement is that your template includes a layout component.
 
-In addition, any astro template that offer `./src/layouts/MarkdownPostLayout.astro` and use the default blog file structure (please refer to the code block above) is compatiable with `noblog`.
+This means you can use:
+
+- ✅ Any existing Astro blog template
+- ✅ Your custom Astro theme
+- ✅ Popular Astro themes from the community
+- ✅ The starter template: **[nobloger](https://github.com/humbornjo/nobloger)**
+
+### Layout Customization
+
+By default, Noblog uses `../../layouts/MarkdownPostLayout.astro` as the layout path. You can customize this using the `--layout` option:
+
+```bash
+# Use a custom layout
+noblog --layout ../../layouts/BlogLayout.astro
+
+# Use with custom save paths
+noblog ./content/blog/ ./content/blog/subpages/ --layout ../../../layouts/CustomLayout.astro
+```
 
-# Millstone
+**Important:** The layout path is relative to the posts directory where your markdown files are saved. For example:
+- If your save path is `./src/pages/posts/`, the default layout path `../../layouts/MarkdownPostLayout.astro` points to `./src/layouts/MarkdownPostLayout.astro`
+- If you change the save path to `./content/blog/`, you might need `--layout ../../layouts/CustomLayout.astro` to point to `./content/layouts/CustomLayout.astro`
 
-- \[2024.07.08\] fuck around
-- \[2024.07.20\] generate github flavored markdown
-- \[2024.09.04\] at least it worked
+Adjust the layout path based on where your Astro layout files are located relative to your posts directory.
 
-# Reference
+## 🙏 Acknowledgments
 
-I really appreciate their work and effort. I stealed and refactored some :)
+Built upon the excellent work of these projects:
 
-- [notion api](https://developers.notion.com/reference/intro)
-- [notion sdk](https://developers.notion.com/docs/getting-started)
-- [notion-to-md](https://github.com/souvikinator/notion-to-md)
-- [notablog](https://github.com/dragonman225/notablog)
-- [astro-notion-blog](https://github.com/otoyo/astro-notion-blog)
+- [Notion API](https://developers.notion.com/reference/intro) - Official Notion API documentation
+- [Notion SDK](https://developers.notion.com/docs/getting-started) - Notion's official SDK
+- [notion-to-md](https://github.com/souvikinator/notion-to-md) - Notion to Markdown converter
+- [notablog](https://github.com/dragonman225/notablog) - Original inspiration
+- [astro-notion-blog](https://github.com/otoyo/astro-notion-blog) - Astro + Notion integration