|
1 | | -# Emacs Org-mode Blog Setup |
| 1 | +# Org-Mode Blog |
2 | 2 |
|
3 | | -This blog is configured in your Doom Emacs with the Claude Code documentation style. |
| 3 | +Static blog generator powered by Emacs Org publish, with shell-based build scripts and GitHub Pages deployment. |
4 | 4 |
|
5 | | -## Usage |
| 5 | +## Prerequisites |
6 | 6 |
|
7 | | -### Create a new blog post |
| 7 | +- Emacs |
| 8 | +- Node.js 16+ and npm |
| 9 | +- Python 3 (for local preview server) |
8 | 10 |
|
9 | | -- Use `SPC B n` (capital B) to create a new post |
10 | | -- Enter the title when prompted |
11 | | -- The post will be created with automatic filename and filled template |
12 | | - |
13 | | -### Publish your blog |
14 | | - |
15 | | -- Use `SPC B p` (capital B) to publish all posts |
16 | | -- Files will be generated in `~/blog/public/` |
17 | | -- Run `./build.sh` for command-line building |
18 | | -- Run `make build-prod` for production build with minification |
19 | | - |
20 | | -### Directory Structure |
21 | | - |
22 | | -``` |
23 | | -~/blog/ |
24 | | -├── posts/ # Your org-mode blog posts |
25 | | -├── static/ # CSS, JS, and other assets |
26 | | -│ ├── css/ # Stylesheets |
27 | | -│ ├── js/ # JavaScript files |
28 | | -│ └── favicon.svg # Site favicon |
29 | | -├── templates/ # Post templates |
30 | | -├── public/ # Generated HTML output |
31 | | -├── .github/ # GitHub Actions workflows |
32 | | -│ └── workflows/ |
33 | | -│ ├── publish.yml # Main deployment workflow |
34 | | -│ ├── pr-preview.yml # Pull request previews |
35 | | -│ └── ci.yml # Continuous integration |
36 | | -├── build.sh # Build script |
37 | | -├── generate-sitemap.sh # Sitemap generator |
38 | | -├── minify.sh # Asset minification |
39 | | -├── Makefile # Build automation |
40 | | -├── .blogrc # Configuration file |
41 | | -└── htmlize.el # Syntax highlighting support |
42 | | -``` |
43 | | - |
44 | | -### Configuration |
45 | | - |
46 | | -The blog can be configured through environment variables in `.blogrc`: |
| 11 | +## Quick Start |
47 | 12 |
|
48 | 13 | ```bash |
49 | | -export BLOG_AUTHOR="your-name" |
50 | | -export BLOG_EMAIL="your-email@example.com" |
51 | | -export BLOG_URL="https://your-domain.com" |
52 | | -export MINIFY_ASSETS="false" # Set to "true" for production |
53 | | -``` |
54 | | - |
55 | | -### Workflow |
56 | | - |
57 | | -1. Create new post: `SPC B n` (capital B) in Doom Emacs |
58 | | -2. Write your content in org-mode |
59 | | -3. Publish locally: `SPC B p` (capital B) in Doom Emacs or run `./build.sh` |
60 | | -4. Serve locally: `make serve` or `cd ~/blog/public && python -m http.server` |
61 | | -5. Deploy: Push to GitHub, automatic deployment via Actions |
62 | | - |
63 | | -### Working with Drafts |
64 | | - |
65 | | -To create draft posts that won't be published: |
66 | | - |
67 | | -1. Add `#+DRAFT: true` to the post header |
68 | | -2. When ready to publish, change to `#+DRAFT: false` or remove the line |
69 | | -3. Draft posts are excluded from the sitemap and won't be built |
70 | | - |
71 | | -Example draft post header: |
72 | | - |
73 | | -```org |
74 | | -#+TITLE: My Draft Post |
75 | | -#+DATE: <2025-01-01> |
76 | | -#+AUTHOR: bytenoob |
77 | | -#+DRAFT: true |
78 | | -#+OPTIONS: toc:t num:nil |
| 14 | +npm ci |
| 15 | +cp .blogrc.example .blogrc |
| 16 | +./build.sh |
| 17 | +make serve |
79 | 18 | ``` |
80 | 19 |
|
81 | | -### Features |
82 | | - |
83 | | -The blog includes: |
84 | | - |
85 | | -- **Modern Design**: Clean, responsive design inspired by Claude Code docs |
86 | | -- **Automatic Features**: |
87 | | - - Archive/index generation with newest-first sorting |
88 | | - - Date extraction from filenames and metadata |
89 | | - - Cache busting for CSS/JS assets |
90 | | - - Sitemap.xml generation for SEO |
91 | | - - 404 error page |
92 | | -- **Developer Experience**: |
93 | | - - Colored build output with progress indicators |
94 | | - - Production build with asset minification |
95 | | - - GitHub Actions for CI/CD |
96 | | - - Pull request preview builds |
97 | | -- **User Experience**: |
98 | | - - Dark mode support |
99 | | - - Mobile responsive design |
100 | | - - Fast page loads with optimized assets |
101 | | - - Comprehensive syntax highlighting |
102 | | - |
103 | | -### Syntax Highlighting |
104 | | - |
105 | | -The blog supports syntax highlighting for code blocks through a dual approach: |
106 | | - |
107 | | -1. **Server-side highlighting** (via htmlize.el): |
108 | | - - Emacs Lisp, Python, JavaScript, Shell, HTML/CSS, SQL |
109 | | - |
110 | | -2. **Client-side fallback** (via JavaScript): |
111 | | - - Go, Rust, JSON, YAML |
112 | | - - Automatically applied for better accuracy |
| 20 | +Open `http://localhost:8000`. |
113 | 21 |
|
114 | | -To add support for more languages: |
| 22 | +## Common Commands |
115 | 23 |
|
116 | | -1. Install the Emacs mode in `~/.config/doom/packages.el` |
117 | | -2. Run `doom sync` to install |
118 | | -3. Test with `./build.sh` |
119 | | -4. If needed, extend the JavaScript fallback in `static/js/blog.js` |
| 24 | +- `make build` or `npm run build`: Build site into `public/` |
| 25 | +- `make build-prod` or `npm run build:prod`: Build and minify assets |
| 26 | +- `make serve` or `npm run serve`: Build and preview locally |
| 27 | +- `make dev`: Watch `posts/` and `static/`, then rebuild on change |
| 28 | +- `npm run format`: Format JS/CSS/JSON/MD/YAML |
| 29 | +- `npm run format:check`: Check formatting |
120 | 30 |
|
121 | | -### GitHub Actions |
| 31 | +## Project Layout |
122 | 32 |
|
123 | | -The blog includes three workflows: |
| 33 | +- `posts/`: Org source files for posts and pages |
| 34 | +- `static/`: CSS, JS, images, favicon, robots |
| 35 | +- `templates/`: Post template(s) |
| 36 | +- `build.el`: Org publish configuration |
| 37 | +- `build.sh`, `minify.sh`, `generate-sitemap.sh`: Build pipeline scripts |
| 38 | +- `public/`: Generated output (do not edit directly) |
124 | 39 |
|
125 | | -1. **publish.yml**: Main deployment to GitHub Pages |
126 | | - - Triggers on push to main branch |
127 | | - - Builds site with production optimizations |
128 | | - - Deploys to GitHub Pages |
| 40 | +## Writing Posts |
129 | 41 |
|
130 | | -2. **pr-preview.yml**: Preview builds for pull requests |
131 | | - - Generates preview artifacts |
132 | | - - Comments on PR with build statistics |
| 42 | +Create posts in `posts/` using `YYYY-MM-DD-slug.org` naming. Include: |
133 | 43 |
|
134 | | -3. **ci.yml**: Continuous integration checks |
135 | | - - Validates Org file syntax and metadata |
136 | | - - Runs ShellCheck on scripts |
137 | | - - Tests build process |
138 | | - - Checks for broken internal links |
| 44 | +- `#+TITLE:` |
| 45 | +- `#+AUTHOR:` |
| 46 | +- `#+DATE:` |
139 | 47 |
|
140 | | -### Deployment |
| 48 | +Set `#+DRAFT: true` to keep a post unpublished. |
141 | 49 |
|
142 | | -#### GitHub Pages |
| 50 | +## Deployment |
143 | 51 |
|
144 | | -1. Enable GitHub Pages in repository settings |
145 | | -2. Set source to "GitHub Actions" |
146 | | -3. Push to main branch to trigger deployment |
| 52 | +Push to `main` to trigger `.github/workflows/publish.yml` and deploy to GitHub Pages. |
147 | 53 |
|
148 | | -#### Custom Domain |
| 54 | +For configuration, use `.blogrc` and/or repository secrets (`BLOG_URL`, `BLOG_AUTHOR`, `BLOG_EMAIL`). |
149 | 55 |
|
150 | | -1. Add `CNAME` file to `static/` directory |
151 | | -2. Update `BLOG_URL` in `.blogrc` or GitHub Secrets |
152 | | -3. Configure DNS settings with your domain provider |
| 56 | +## CI Checks |
153 | 57 |
|
154 | | -### Troubleshooting |
| 58 | +PRs run `.github/workflows/ci.yml`, including: |
155 | 59 |
|
156 | | -- **Build errors**: Check `build.sh` output for detailed error messages |
157 | | -- **Syntax highlighting issues**: Ensure required Emacs modes are installed |
158 | | -- **GitHub Actions failures**: Check workflow logs in Actions tab |
159 | | -- **Local preview issues**: Ensure Python 3 is installed for local server |
| 60 | +- Org metadata validation |
| 61 | +- Shell script linting |
| 62 | +- Build verification |
| 63 | +- Internal HTML link checks |
0 commit comments