MarkdownCms 0.2.0
dotnet add package MarkdownCms --version 0.2.0
NuGet\Install-Package MarkdownCms -Version 0.2.0
<PackageReference Include="MarkdownCms" Version="0.2.0" />
paket add MarkdownCms --version 0.2.0
#r "nuget: MarkdownCms, 0.2.0"
// Install MarkdownCms as a Cake Addin #addin nuget:?package=MarkdownCms&version=0.2.0 // Install MarkdownCms as a Cake Tool #tool nuget:?package=MarkdownCms&version=0.2.0
Markdown CMS
Markdown CMS is a Nuget package that let's you use GitHub hosted markdown files in a simple web site.
Should I use Markdown CMS
Maybe.
- Do you have 1000s or 100s of pages? Probably not.
- Do you have a
real CMS
in placed today? Probably not. - Do you care about
pixle level placement
? Probably not. - Do you have a few pages like technical instructions? That's why I built it.
- Do you have multiple instances, perhaps deployed by multiple customers, that need different content? That's why I built it.
See it in action
- A quick example is available here
- We wanted each of our customers to be able to quickly update their documentation
- We wanted it to look "nice". Doesn't have to be "perfect".
- The default content is here
home.md
gets rendered in the main framelinks.md
gets rendered in theMore Information
frame- Our whitepaper and license agreement get rendered in the main frame if you click on the links
- It's fast because we cache the MD and HTML content
- If something like that meets your needs, please try it out and give me feedback
- If not, thanks for dropping by
Quick Start
- Create a Codespace from this repo
dotnet run
code Program.cs
Using the HTML
The HTML is generally usable after the conversion. Two things that need to be dealt with are images
and links to other markdown files
.
The first step to dealing with these issues effectively is to make sure you have standards in place for how to specify links and images in your markdown. For example, GitHub will render the following links correctly ./images/pb.jpg
, images/pb.jpg
, and /docs/images/pb.jpg
. The same is true for links to other markdown: contact.md
, ./contact.md
, and /docs/contact.md
are all valid.
Using the full path (/docs/images/pb.jpg
) has the advantage of still working if you move your md file from the root to a directory. ./images/pb.jpg
seems to be very common as well. I recommend standardizing on one or the other.
Whatever you choose, choose one so that you can replace the HTML easily. Because the HTML is generated from the markdown files (using Markdig
), the HTML is very clean. It's easy to search on "./images/
and safely replace it.
You may also have the need to add classes to your HTML so that it renders correctly in your site. For example, you might want to replace <h1>
with <h3 class='card-title text-primary'>
.
This is pretty easy to do in C#
html = html.Replace("<h1>", "<h3 class='card-title text-primary'>").Replace("</h1>", "</h3>");
One of the values of Markdown CMS is it caches the file from GitHub and the generated HTML. To customize the HTML that is created and cached, do the following.
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>");
}
If your markdown files are not standardized, you will get a lot of render and navagation errors. They are easy to fix, but if you can't drive standards, Markdown CMS won't be a good experience. It's pretty easy with a few documents. Lots of documents, modified by lots of people is more problematic.
Using in your project
Install MarkdownCms from Nuget
dotnet add package MarkdownCms --version 0.1.0
Open Program.cs for an example
code Program.cs
Support
This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new issue.
For help and questions about using this project, please open a GitHub issue.
Contributing
This project welcomes contributions and suggestions. Please see contributing for more details.
This project has adopted the Contributor Covenant Code of Conduct. Please see our code of conduct for more details.
Trademarks
This project may contain trademarks or logos for projects, products, or services. Any use of third-party trademarks or logos are subject to those third-party's policies.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net7.0
- Markdig (>= 0.34.0)
- Microsoft.Extensions.Logging.Console (>= 7.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.2.0 | 181 | 2/8/2024 |