Posts in the 'downr' category

The posts below all relate to the topic you selected.

Since downr is built using Blazor WebAssembly, I'll be loading components into areas of the page. Given I wanted to continue to use Google Analytics to track each page (and component) load, simply slapping the Google Analytics tracking JavaScript code on my index.html page isn't sufficient. I'll need to track traffic on a component-by-component basis. This post walks through the usage of the Google Analytics feature in downr, and describes how I built it.

How to enable Google Analytics in downr

Enabling GA support is as simple as changing one setting in appsettings.json. Here's my file before I added GA support:

{
  "downr": {
    "title": "bradygaster.com",
    "rootUrl": "https://bradygaster.com",
    "pageSize": 4,
    "author": "brady gaster",
    "indexPageText": "Hi! I'm a christian dad who lives near Seattle, works at Microsoft with the talented folks on the .NET team, tinkers with MIDI hardware, and makes loud music with computers.",
    "imagePathFormat": "https://bradygasterdotcom.azureedge.net/posts/{0}/media/"
  }
}

Here's the appsettings.json file with support added:

{
  "downr": {
    "title": "bradygaster.com",
    "rootUrl": "https://bradygaster.com",
    "pageSize": 4,
    "author": "brady gaster",
    "indexPageText": "Hi! I'm a christian dad who lives near Seattle, works at Microsoft with the talented folks on the .NET team, tinkers with MIDI hardware, and makes loud music with computers.",
    "imagePathFormat": "https://bradygasterdotcom.azureedge.net/posts/{0}/media/",
    "googleTrackingCode" : "UA-133394-2"
  }
}

Once downr users add a value for the googleTrackingCode, Google Analytics lights up. It's that simple.

Tracking code in components? No.

The first thing I thought was, let's put the tracking code into each component. This was far too easy a solution to really work. What if I build in more features over time, resulting in nested components? I don't want to repeat the same JavaScript code at various points throughout the site - that'd get bloated quickly.

Not to mention the fact that the Razor compiler knows this isn't a good idea and lets me know pretty clearly why.

Tracking script error in a .razor file

Thanks, team, for saving me from doing something not-quite-right here!

How tracking was implemented

The implementation wasn't too complex. Before I wrote the code to support it, I established a few assumptions & goals:

  1. I'm going to want to add support for Azure Application Insights, so whatever I do, I need it to not "tie" me to Google Analytics as my only means of tracking.
  2. downr users will want to easily configure their own GA code.
  3. The tracker should be reusable in other components.

The first step was to add the configuration property to the DownrOptions class, which provides IOption<T>-style configuration throughout the downr's components, services, and controllers.

/// <summary>
/// This value is optional. If it is provided in your configuration, the Google tracking
/// JavaScript code will be injected into your pages.
/// </summary>
/// <value></value>
public string GoogleTrackingCode { get; set; }

The index.html page needs to be outfitted with the remote script enabling Google Analytics tracking to occur. This is okay for index.html - I'm not actually executing the tracking behavior, just including the script as a dependency.

<script async src='https://www.google-analytics.com/analytics.js'></script>

I'll also add a small JavaScript function to site.js. This code executes the GA tracking functionality. By wrapping the tracking code in this manner, the Blazor components can use the IJSRuntime service to call the tracking script when they load.

window.trackWithGoogle = (ua) => {
    window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
    ga('create', ua, 'auto');
    ga('send', 'pageview');
};

The Tracker.razor component code is obviously very minimal - it serves the purpose of executing the tracking code if I've enlisted in it via configuring my site for it. Tracker's implementation leaves room for me to dial in another tracker when I'm ready.

@inherits ComponentBase
@using downr
@inject DownrOptions options
@inject IJSRuntime JSRuntime

@code {
    protected override async Task OnInitializedAsync()
    {
        if(!string.IsNullOrEmpty(options.GoogleTrackingCode))
        {
            await JSRuntime.InvokeVoidAsync("trackWithGoogle", options.GoogleTrackingCode);
        }
    }
}

By configuring my site with the googleTrackingCode property, I enlist in GA tracking, and the trackWithGoogle script is called each time any component including the Tracker component renders.

Tracking per-component

Now, I can include Tracker in my other components. The list isn't long - downr only has two (currently) main pages:

  • Index.razor, which renders the list of posts
  • Posts.razor, which is what you see when you click to read a post

Tracker is included both at the bottom of Index.razor to track when the home page is loaded:

    <button id="loadMorePostsButton" class="btn btn-secondary btn-center" @onclick="OnLoadMoreButtonClicked">more</button>
  </div>
</div>

<Tracker/>

And at the bottom of Posts.razor, so each click-through to an article can be tracked.

@page "/posts/{slug}"
@using downr.Models
@inject HttpClient Http
@inject Microsoft.Extensions.Options.IOptions<downr.DownrOptions> downrOptions

<div class="text">
    <h1 class="display-4">@Post.Title</h1>
    <div id="post">
        @((MarkupString)Post.Content)
    </div>
</div>

<Tracker/>

Summary

When you have needs for tracking scripts within a Blazor app, there are definitely some things you'll need to consider, but there are also some great customization opportunities for how you track behavior and traffic in your site. This post examines how I accomplished tracking with downr. Soon I'll add support for Azure Application Insights (or I'll accept a pull request if you'd like to implement it), and add a subsequent blog post describing how you can enlist.

 

Creating new posts

posted one year ago in downr

As mentioned in the introduction, one of the goals of downr is that it feels natural for developer bloggers who use Visual Studio Code and the .NET CLI. As such, we've created a .NET tool that contains a blog post template.

Install the downr tools

To make your downr blogging experience feel as natural as developing with .NET Core, run the following command to install the downr CLI tools.

dotnet new --install downr-tools::1.0.0

Installing the tools will place a simple template into your dotnet new template list named post.

Create a new post

With the tools installed, creating a new post is simple. Open a terminal window in the wwwroot\posts folder of your site and execute this dotnet new command:

dotnet new post --output new-post

This will create a the following folder structure underneath your posts folder:

|-- posts
    |-- new-post
        |-- index.md
        |-- media
            |-- placeholder.png

The index.md file will contain the defaults if you don't provide any parameters. From executing the command above, you'd get an index.md with this content:

---
title: My new downr blog post
slug: my-new-downr-blog-post
author: author-name
lastModified: 2020-01-19 12:15:38
pubDate: 2020-01-19 12:15:38
categories: blog,post,article
description: This is a description of the post.
---

Your content here in [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) format.

![Sample image](media/placeholder.png)

Post template CLI parameters

If you'd prefer to use the template's CLI parameters to set your metadata up front, you can find out descriptions of the parameters via the dotnet new post --help command, which results with the following output:

Options:                                                                                                      
    -t|--title        The title of your blog post                                                               
                        string - Optional                                                                         
                        Default: My new downr blog post                                                           

    -s|--slug         A URL-friendly slug that will make your post easy to find                                 
                        string - Optional                                                                         
                        Default: my-new-downr-blog-post                                                           

    -au|--author      The name you wish to be recognized by on the blog                                         
                        string - Optional                                                                         
                        Default: author-name                                                                      

    -c|--categories   A comma-separated list of categories in which your blog will appear                       
                        string - Optional                                                                         
                        Default: blog,post,article                                                                

    -d|--description  A description of your site. This will be used in the site RSS feed to introduce your post.
                        string - Optional                                                                         
                        Default: This is a description of the post.

So, you could get started with a new post, complete with the metadata to describe the post rather than the boring defaults, using something like:

dotnet new post -t "My exciting new post" -au happy-blogger -s my-exciting-new-post -o my-exciting-new-post -d "This post is going to be so awesome and you will be a better person for reading it."

If you're a detail-oriented CLI user who isn't afraid of that verbose a command, the results are like blogging zen. A fully-ready document awaiting your creative output.

---
title: My exciting new post
slug: my-exciting-new-post
author: happy-blogger
lastModified: 2020-01-19 12:26:33
pubDate: 2020-01-19 12:26:33
categories: blog,post,article
description: This post is going to be so awesome and you will be a better person for reading it.
---

Now, my metadata needs are satisfied, and I can start writing.

 

downr 3.0

posted one year ago in downr

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 to create a blogging engine that:

  • Is built using .NET 3.1 so it can run anywhere
  • Feels natural for developer bloggers who use Visual Studio Code to author their content in Markdown
  • Supports being CI/CD'd anywhere
  • Feels natural to .NET developers who frequently use the dotnet CLI
  • Is open source and available on GitHub
  • Is build using Blazor WebAssembly (because why not?)

Getting downr Running Locally

Getting downr running on a development workstation is easy. Open your favorite terminal window and run this:

git clone https://github.com/bradygaster/downr.git
cd downr/server
dotnet run

Blogging with downr

Blogging with downr is deliberately very simple - you just write Markdown. downr operates on two conventions - how you organize your markdown and content files and some simple YAML metadata in each post's Markdown file.

Example post structure

Consider this post, the introduction to downr. This post's slug is introducing-downr-3. This post's folder structure on disk looks like this. You place the Markdown files into the Server\wwwroot\posts folder.

|-- introducing-downr-3
    |-- index.md
    |-- media
        |-- img1.png
        |-- img2.png

This ensures all your posts follow a nice, neat conventional folder structure. Once you have a gaggle of posts published to your site, it'll be all tidy like this:

|-- wwwroot
    |-- posts
        |-- a-post-with-no-pictures
            |-- index.md
        |-- introducing-downr-3
            |-- index.md
            |-- media
                |-- img1.png
                |-- img2.png
        |-- some-other-post
            |-- index.md
            |-- media
                |-- pic1.png
                |-- pic2.png
                |-- pic3.png

Post Metadata

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
description: Each post should have a description for the index page and for the RSS feed
---

Customizing your site

If you want to customize the style or HTML layout, you have 4 files to edit in the Client folder:

  • appsettings.json
  • Pages/Index.razor
  • Pages/Posts.razor
  • wwwroot/index.html

Site-wide data can be edited using the downr section of appsettings.json. Customize this to change the title and banner of your site.

"Downr": {
    "title" : "downr",
    "rootUrl" : "http://downr.azurewebsites.net",
    "pageSize": 2,
    "author": "the downr team",
    "indexPageText": "downr is a dirt-simple blogging tool written for people who like to author their content in markdown"
}

Obviously, you can customize your site all you want, but if you're simply into blogging with Markdown you never need to look at the source code.

Dependencies

downr was created using these excellent open-source libraries:

Contributing

Contributions to downr are welcome and encouraged. Fork the downr GitHub repository and submit pull requests to your heart's content.

Naming Disclaimer

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.

 

Introducing downr

posted 4 years ago in downr

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.

downr repo 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 localhost:5000.

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 index.md
  • Images and other media are stored in the media subfolder for each post's folder
  • All posts' content are stored in the top-most posts folder in the repository
  • Customization is done within the css and templates folders

The screen shot below shows the default folder structure.

downr folder structure

Post Metadata

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 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.

Image path fix-ups

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 /posts/introducing-downr/media/folder-structure.png.

Project Details

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 yo aspnet template.
  • NuGet dependencies:
  • Grunt is used to perform the build, during which:
    • The site.css is cleared and restored from the root css folder content
    • The posts folder from the wwwroot folder is deleted and restored from the root's posts folder. The root posts folder is where bloggers should commit Markdown content.
    • The Razor templates from the templates folder in the project root are copiled into the src\Views folder prior to compilation
  • Bower is used to install the client-side JavaScript resources, specifically, Bootstrap, as this is used for the client-side experience construction
  • 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:

  1. Fork the GitHub repository

  2. Clone your fork

  3. Create a new Web App using the Azure portal

  4. Enable local Git repository publishing via the Azure portal

    Local Git repo setup

  5. Copy the Web App's Git repository URL to your clipboard

    Copy Git URL

  6. Use the copied URL as the URL of a new remote for your site's local repository

     git remote add azure [your copied url]
    
  7. 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 templates folder.

  8. 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
    
  9. 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.

Redeploying

Contributing

Contributions to downr are welcome and encouraged. Fork the downr GitHub repository and submit pull requests to your heart's content.

Naming Disclaimer

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.