downr is a very simple blogging engine written for people who like using Markdown to write content and Git to maintain their source code and/or content files. The goals of downr are as follows:
- Enable bloggers with Markdown syntax-driven blogging
- Create an enjoyable experience for developer bloggers using Visual Studio Code or the Visual Studio Markdown Editor extension to author their content and maintain their site
- Support Git deployment to Azure App Service*
- Separate the responsibilities of maintaining presentation and content from the source code of the site
downr is written using .NET Core, and is packaged and deployed using NPM, Bower, and Grunt. It is open-source and available on GitHub at http://github.com/bradygaster/downr.
* Azure isn't a deployment target requirement. So long as your desired cloud provider supports NPM, Grunt, and ASP.NET Core, you're cool.
Getting downr Running Locally
Getting downr running on a development workstation is easy. The project is open source and available on GitHub.
Simply clone the repository:
git clone https://github.com/bradygaster/downr.git
If you have Visual Studio Code installed, the easiest way to run the code locally is to open the root folder up in code from the command line once the repository has been cloned.
cd downr code .
If you don't have Visual Studio Code installed or want to run the app locally from the command line alone, simply use the
dotnet command line utility to restore the packages, build the app, and run it at
dotnet restore dotnet build dotnet run
Blogging with downr
Blogging with downr is deliberately very simple: you basically just write Markdown. If you want to customize the style or HTML layout, you have 3 files to edit. Obviously, you can customize it all you want, but if you're simply into blogging with Markdown you never need to look at the source code.
Here are the basic conventions of blogging with downr:
- The Markdown and media assets for each post are stored in individual folders named according to the posts' slugs
- Each post must have a YAML header containing post metadata
- Each post's content is authored in an individual Markdown file named
- Images and other media are stored in the
mediasubfolder for each post's folder
- All posts' content are stored in the top-most
postsfolder in the repository
- Customization is done within the
The screen shot below shows the default folder structure.
The top section of each Markdown file must contain a YAML header with some simple metadata elements. All of these elements are required. The YAML below demonstrates this convention.
--- title: Introducing downr slug: introducing-downr author: bradygaster lastModified: 2017-01-06 12:00:00 pubDate: 2017-01-06 12:00:00 categories: downr ---
Image Path Fix-ups
As demonstrated by this file earlier, the path you'd use to link to images should be
posts/introducing-downr/media/[filename]. At run-time, the
src attributes for each image in your posts will be fixed automatically. This enables you to edit and preview your content in Visual Studio Code in exactly the same way it'll be rendered once you publish your blog.
Note how the Markdown source code links to the relative path of the image in the
media subfolder, but in the Chrome F12 tools in the top pane of the screenshot the image path is fixed up to be relative to the site's root at
downr was created using a collection of open-source web frameworks and tools. Here's a quick synopsis of the project's architecture.
- Initial project structure created using Yeoman's
- NuGet dependencies:
- Markdig is used for Markdown-to-HTML conversion
- YamlDotNet is used to parse the YAML headers in post Markdown files
- The HTML Agility Pack for .NET Core is used for the image path fix-ups
- Grunt is used to perform the build, during which:
site.cssis cleared and restored from the root
postsfolder from the
wwwrootfolder is deleted and restored from the root's
postsfolder. The root
postsfolder is where bloggers should commit Markdown content.
- The Razor templates from the
templatesfolder in the project root are copiled into the
src\Viewsfolder prior to compilation
- Obviously, NPM is being used to install the build resources
Publishing to Azure
Included in the source code is an Azure Kudu deployment script (a
.deployment file). You can learn more about these files on the Kudu Wiki. This file specifies the
src folder as the project folder.
Getting started with downr running on Azure App Service is relatively easy:
Fork the GitHub repository
Clone your fork
Create a new Web App using the Azure portal
Enable local Git repository publishing via the Azure portal
Copy the Web App's Git repository URL to your clipboard
Use the copied URL as the URL of a new remote for your site's local repository
git remote add azure [your copied url]
Add or edit posts in the
postsfolder, and customize your style via the root
cssfolder. If you need to change the layout or want to customize the navbar or sidebar edit the
.cshtmlfiles in the
Commit your files to your local Git repository and then push them to your azure remote
git add . git commit -m 'added content or customized style' git push azure master
Once the publish completes you should see new content
Note: In some cases, the very first publish to Azure fails to copy the content and style files. If this happens or you see something unexpected, use the Azure portal to redeploy your previous deployment. The screenshot below demonstrates how you can re-deploy your initial publish with one click in the portal.
Contributions to downr are welcome and encouraged. Fork the downr GitHub repository and submit pull requests to your heart's content.
Note: Product naming is difficult. I noticed that there were a few other projects out there named similarly to this one. The dotnet markdown blogging tool known as downr has no implied or accidental relationship to any of these other awesome projects.