MarkdownCms 0.2.0

Markdown CMS

Markdown CMS 是一个 NuGet 包，允许您在一个简单的网站上使用 GitHub 托管 markdown 文件。

我应该使用 Markdown CMS 吗？

也许吧。

• 你有成千上万的页面或者几百个页面吗？可能不是。
• 你今天已经有了 真正的 CMS 吗？可能没有。
• 你对 像素级别的定位关心吗？可能不。
• 你有一些页面，比如技术说明？这就是我构建它的原因。
• 你有多重实例，可能由多个客户部署，需要不同的内容？这就是我构建它的原因。

看看它的实际应用

• 的一个快速示例在这里 这里
  • 我们希望每位客户都能够快速更新他们的文档
  • 我们希望它看起来“不错”。不需要“完美”。
• 默认内容在这里 这里
  • home.md 在主框架中渲染
  • links.md 在 更多信息 框架中渲染
  • 点击链接时，我们的白皮书和许可协议将渲染在主框架中
• 它很快，因为我们缓存了 MD 和 HTML 内容
• 如果此类内容符合您的需求，请尝试它并提供反馈
• 如果不适合，感谢您的光临

快速开始

• 从本仓库创建一个Codespace
• dotnet run
• 编写 Program.cs 中的代码

使用 HTML

HTML 转换后通常可以正常使用。需要处理的两件事是 图片 和 其他 markdown 文件的链接。

解决这些问题的第一步是确保你在 markdown 中如何指定链接和图片有标准。例如，GitHub 可以正确渲染以下链接 ./images/pb.jpg，images/pb.jpg 和 /docs/images/pb.jpg。其他 markdown 的链接也是如此：contact.md，./contact.md 和 /docs/contact.md 都是有效的。

使用完整的路径（/docs/images/pb.jpg）的优点是，即使你将 md 文件从根目录移动到某个目录中，它仍然可以正常工作。./images/pb.jpg 也似乎非常常见。我建议统一使用其中一种。

无论你选择哪种方式，都要选择一种，以便可以轻松地替换 HTML。因为 HTML 是由 markdown 文件生成的（使用 Markdig），所以 HTML 非常干净。在 "./images/ 上进行搜索和替换它是安全的。

你可能还需要将类添加到 HTML 中，以便在网站上正确渲染。例如，你可能想将 <h1> 替换为 <h3 class='card-title text-primary'>。

这在使用 C# 时非常容易做到。

html = html.Replace("<h1>", "<h3 class='card-title text-primary'>").Replace("</h1>", "</h3>");

Markdown CMS 的一点价值在于它缓存了 GitHub 上的文件和生成的 HTML。要自定义创建和缓存的 HTML，请执行以下操作。

public class Program
{
    private static async Task Main
    {
        // set the content GitHub repository
        MdContent.ContentRepo = "bartr/markdowncms";

        // add your custom function(s) - in order!
        MdContent.AddHtmlFunction(ReplaceH1s);

        // your other code
    }

    // custom HTML Function
    private static string ReplaceH1s(string html)
    {
        return html.Replace("<h1>", "<h3 class='card-title text-primary'>").Replace("</h1>", "</h3>");
    }

如果你的 markdown 文件不规范，你将会遇到许多渲染和导航错误。它们很容易修复，但如果无法制定标准，Markdown CMS 的体验可能并不好。对于少量文档来说非常简单。大量由多人修改的文档则更为复杂。

在项目中使用

从 Nuget 安装 MarkdownCms

• dotnet add package MarkdownCms --version 0.1.0

打开 Program.cs 查看示例

• 编写 Program.cs 中的代码

支持

本项目使用 GitHub Issues 跟踪错误和功能请求。在提交新问题之前，请搜索现有问题，以避免重复。对于新问题，请以新问题的方式提交你的错误或功能请求。

有关使用本项目的帮助和问题，请创建 GitHub issue。

贡献

本项目欢迎贡献和建议。请参阅 贡献指南 获取更多详细信息。

本项目采用了 贡献者守则。请参阅 我们守则 获取更多详细信息。

商标

本项目可能包含项目、产品或服务的商标或徽标。任何使用第三方商标或徽标的行为均受第三方政策约束。