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:
* 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 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 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:
mediasubfolder for each post's folder
postsfolder in the repository
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 ---
As demonstrated by this file earlier, the path you'd use to link to images should be
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.
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.
templatesfolder in the project root are copiled into the
src\Viewsfolder prior to compilation
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
posts folder, and customize your style via the root
css folder. If you need to change the layout or want to customize the navbar or sidebar edit the
.cshtml files 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.