Skip to content

STATIC_HTML_GUIDE.md

Latest commit

 

History

History
277 lines (198 loc) · 5.46 KB

STATIC_HTML_GUIDE.md

File metadata and controls

277 lines (198 loc) · 5.46 KB

静态 HTML 文件生成指南

📄 功能说明

系统可以为每篇文章生成独立的 HTML 文件，方便：

  • 直接查看和管理
  • SEO 优化
  • 静态部署
  • 离线访问

🚀 使用方法

方法 1：生成所有文章（推荐）

  1. 登录后台
  2. 进入文章管理页面
  3. 点击顶部的 "📄 生成 HTML" 按钮
  4. 确认生成
  5. 等待文件自动下载

方法 2：生成单篇文章

  1. 在文章列表中
  2. 点击文章右侧的 "📄" 按钮
  3. 文件自动下载

📁 文件组织

1. 创建 posts 文件夹

在项目根目录创建 posts 文件夹：

你的项目/
├── index.html
├── about.html
├── css/
├── js/
└── posts/          ← 新建这个文件夹
    ├── post-1-自我介绍.html
    ├── post-2-javascript-异步编程指南.html
    └── ...

2. 移动下载的文件

将下载的所有 HTML 文件移动到 posts 文件夹中。

3. 文件命名规则

post-{文章ID}-{标题}.html

例如：

  • post-1-自我介绍.html
  • post-2-javascript-异步编程指南.html
  • post-3-css-grid-布局实战.html

🔗 更新首页链接

生成 HTML 后，需要更新首页的文章链接。

自动方式（推荐）

系统会自动生成正确的链接，指向 posts/ 文件夹。

手动方式

如果需要手动调整，修改 js/main.js：

// 查看文章详情
function viewPost(postId) {
    // 旧方式：动态页面
    // window.location.href = `post.html?id=${postId}`;
    
    // 新方式：静态 HTML
    const posts = getPosts();
    const post = posts.find(p => p.id === postId);
    if (post) {
        const filename = postGenerator.generateFilename(post);
        window.location.href = `posts/${filename}`;
    }
}

📊 文件内容

每个生成的 HTML 文件包含：

  • ✅ 完整的文章内容（Markdown 已转换为 HTML）
  • ✅ 文章元数据（标题、日期、作者、分类）
  • ✅ 封面图片
  • ✅ 样式表引用
  • ✅ 返回首页链接
  • ✅ 浏览统计代码

🎨 样式和脚本

生成的 HTML 文件使用相对路径引用：

<link rel="stylesheet" href="../css/style.css">
<script src="../js/analytics.js"></script>

确保项目结构正确：

项目/
├── css/
│   └── style.css
├── js/
│   └── analytics.js
└── posts/
    └── post-1-xxx.html

🔄 更新流程

当文章内容更新时：

1. 后台编辑文章 → 保存
2. 点击该文章的 "📄" 按钮
3. 重新下载 HTML 文件
4. 替换 posts 文件夹中的旧文件

当新增文章时：

1. 后台新建文章 → 保存
2. 点击 "📄 生成 HTML" 或单独生成
3. 将新文件放入 posts 文件夹

当删除文章时：

1. 后台删除文章
2. 手动删除 posts 文件夹中对应的 HTML 文件

🌐 部署到 GitHub Pages

1. 提交文件

git add posts/
git commit -m "Add generated post HTML files"
git push

2. 访问文章

https://你的用户名.github.io/仓库名/posts/post-1-xxx.html

💡 优势

使用静态 HTML 的好处：

  1. SEO 友好

    • 搜索引擎可以直接索引
    • 更好的 SEO 排名

  2. 加载速度快

    • 无需 JavaScript 渲染
    • 直接显示内容

  3. 易于管理

    • 每篇文章独立文件
    • 方便查看和编辑

  4. 离线访问

    • 可以直接打开 HTML 文件
    • 不依赖服务器

  5. 备份方便

    • 文件即备份
    • 易于迁移

⚠️ 注意事项

1. 图片路径

如果使用相对路径的图片：

![图片](../images/photo.jpg)

确保图片文件也在正确的位置。

2. 文件大小

3. 同步问题

  • 静态 HTML 不会自动更新
  • 修改文章后需要重新生成
  • 建议使用脚本自动化

4. 链接更新

  • 首页链接需要指向 posts 文件夹
  • 确保所有内部链接正确

🔧 高级用法

批量生成脚本

创建 generate-posts.js：

const posts = JSON.parse(localStorage.getItem('blogPosts') || '[]');
posts.forEach(post => {
    postGenerator.downloadPost(post);
});

自动化部署

使用 GitHub Actions 自动生成和部署：

name: Generate Posts
on: [push]
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate HTML
        run: node generate-posts.js
      - name: Deploy
        run: |
          git add posts/
          git commit -m "Auto-generate posts"
          git push

📚 相关文档

🆘 常见问题

Q: 生成的文件在哪里？ A: 在浏览器的下载文件夹中。

Q: 如何批量上传到 GitHub？ A: 使用 git 命令：git add posts/ && git commit -m "Add posts" && git push

Q: 文章更新后需要重新生成吗？ A: 是的，需要重新生成并替换旧文件。

Q: 可以自定义模板吗？ A: 可以，编辑 js/post-generator.js 中的模板。

Q: 图片显示不出来怎么办？ A: 检查图片路径是否正确，建议使用图床服务。

提示：生成 HTML 后，记得将文件放入 posts 文件夹并提交到 GitHub！