@Shazwazza

Shannon Deminick's blog all about web development

Articulate 4.3.0 with support for markdown code snippets and syntax highlighting

March 22, 2021 01:52
Articulate 4.3.0 with support for markdown code snippets and syntax highlighting

I'm happy to announce that Articulate 4.3.0 is shipped and includes a great new feature that I've been wanting/needing:

The ability to create markdown based posts with support for GitHub style code fences/snippets and syntax highlighting for (almost) any coding language. See #341.

Now I can finally do away with using Live Writer for my blog and having to manually add css classes to the html for syntax highlighting... yes that's what I've been doing 🤦‍♂️

Upgrading

Once you've updated to the 4.3.0 release, you'll probably need to change the Property Editor of the Articulate Markdown Data Type to be Articulate Markdown editor since it's most likely currently configured to the default/basic Umbraco markdown editor.

You'll then need to update your Post.cshtml theme file to include the correct Prism dependencies. For example, here's the update/diff to the VAPOR theme which adds these dependencies. It's just ensuring that the Prism stylesheet is added to the header and the Prism.js dependencies are appended to the Post.cshtml file.

Once that's all done, your set!

Creating markdown posts

If you didn't already know, Articulate has always had a browser based markdown editor to create posts. You can simply go to your Articulate root URL and go to the path: a-new to load the markdown editor. Previously this editor would require you to authenticate at the end of writing your post (if you weren't already authenticated) but now it requires authentication up-front.

Once it's loaded, it's just a text editor and you can use your all the normal markdown syntax. You can even upload or take photos with the editor 😀

Of course you can just use the back office markdown editor to create or update posts too but I find for quickly getting a post written and published it's faster to use the /a-new editor... and it works on mobile.

Using code fences with syntax highlighting

GitHub's documentation shows how this works. The typical code fence is 3x back-ticks above and below your code snippet. If you want to add language specific syntax highlighting you can use 3x back-ticks + the language name/alias. For example, c# would be: ```cs (or c# or csharp) and JavaScript would be ```js. GitHub's implementation is different from what Articulate uses so it may not be a perfect 1:1 result but should be fairly close. Articulate is using a combination of:

Rendered Examples

There are just rendered examples based on the default prism styles. I wrote this blog post with the Articulate markdown editor so you can see the results.

Here's an example of a rendered csharp code fence:

/// <summary>
/// This is an example of the ArticulateComposer
/// </summary>
[RuntimeLevel(MinLevel = RuntimeLevel.Run)]
public class ArticulateComposer : IUserComposer
{
    public void Compose(Composition composition)
    {
        composition.RegisterUnique<ArticulateRoutes>();
        composition.RegisterUnique<ContentUrls>();
        composition.RegisterUnique<ArticulateDataInstaller>();
        composition.RegisterUnique<ArticulateTempFileSystem>(
            x => new ArticulateTempFileSystem("~/App_Data/Temp/Articulate"));

        // TODO: Register remaining services....
    }
}

Here's an example of a rendered js code fence:

(function () {
    'use strict';

    /**
     * An example of the articulateOptionsManagementController
     * @param {any} $scope
     * @param {any} $element
     * @param {any} $timeout
     */
    function articulateOptionsManagementController($scope, $element, $timeout) {

        var vm = this;
        vm.viewState = "list";
        vm.selectedGroup = null;
        
        // TODO: Fill in the rest....
    }

    var articulateOptionsMgmtComponent = {
        templateUrl: '../../App_Plugins/Articulate/BackOffice/PackageOptions/articulatemgmt.html',        
        controllerAs: 'vm',
        controller: articulateOptionsManagementController
    };

    angular.module("umbraco")
        .component('articulateOptionsMgmt', articulateOptionsMgmtComponent);
})();

Here's an example of a rendered ruby code fence:

class Dog  
  def initialize(breed, name)  
    # Instance variables  
    @breed = breed  
    @name = name  
  end  
  
  def bark  
    puts 'Ruff! Ruff!'  
  end  
  
  def display  
    puts "I am of #{@breed} breed and my name is #{@name}"  
  end  
end

Articulate 4.0.0 released for Umbraco version 8

May 3, 2019 02:37
Articulate 4.0.0 released for Umbraco version 8

It’s finally out in the wild! Articulate 4.0.0 is a pretty huge release so here’s the rundown…

Installation

As a developer, my recommendation is to install packages with Nuget

PM > Install-Package Articulate -Version 4.0.0

If you install from Nuget you will not automatically get the Articulate data structures installed because Nuget can’t talk to your live website/database so once you’ve installed the package and run your site, head over to the “Settings” section and you’ll see an “Articulate” dashboard there, click on the “Articulate Data Installer” tile and you’ll get all the data structures and a demo blog installed.

Alternatively you can install it directly from the Umbraco back office by searching for “Articulate” in the Packages section, or you can download the zip from https://our.umbraco.com/packages/starter-kits/articulate/ and install that in the Umbraco back office. If you install this way all of the data structures will be automatically installed.

Upgrading

I have no official documentation or way of doing this right now 😉. I’ve written up some instructions on the GitHub release here but essentially it’s going to require you to do some investigations and manual updates yourselves. There’s very little schema changes and only small amount of model changes so it shouldn’t be too painful. Good luck!

(note: I have yet to give it a try myself)

Support for Umbraco 8

I think it will come as no surprise that Articulate 4.0.0 is not compatible with any Umbraco v7 version. Articulate 4.0.0 requires a minimum of Umbraco 8.0.2. Moving forward I will only release more Articulate 3.x versions to support v7 based on community pull requests, my future efforts  will be solely focused on 4.x and above for Umbraco 8+.

Theme, Features + Bug fixes

There are several nice bug fixes in this release including a few PR sent in by the community – THANK YOU! 🤗

As for features, this is really all about updating the Themes. Previously Articulate shipped with 6 themes and all of them had a vast range of different features which I never really liked so I spent some time enhancing all of the ones I wanted to keep and made them look a bit prettier too. I’ve removed my own “Shazwazza” theme since it was way outdated to my own site here, plus I don’t really want other people to have the exact same site as me ;) But since that was the most feature rich theme I had to upgrade other ones. I also removed the old ugly Edictum them… pretty sure nobody used that one anyways.

Here’s the theme breakdown (it’s documented too)

image

I’ve also updated the default installation data to contain more than one blog post and an author profile so folks can see a better representation of the blog features on install. And I updated the default images and styling so it has a theme (which is Coffee ☕) and is less quirky (no more bloody rabbit or horse face photos 😛)

Here’s the breakdown of what they look like now…

VAPOR

This is the default theme installed, it is a very clean & simple theme. Originally created by Seth Lilly

theme-vapor

Material

This is based of of Google's material design lite and is based off their their blog template.

theme-material

Phantom

Original theme for Ghost can be found here: https://github.com/Bartinger/phantom/. A nice simple responsive theme.

theme-phantom

Mini

The original author's site can be found here: http://www.thyu.org/www/ but unfortunately their demo site for the Ghost theme is down. The theme's repository is here https://github.com/thyu/minighost.

theme-mini

 

Hope you enjoy the updates!

Articulate 1.0.5 released

December 5, 2014 03:02

Good news!

Today Articulate 1.0.5 has been released which has quite a few issues fixed, here’s the gist:

  • #49 - Doesn't work with Umbraco 7.2
  • #18 - HasProperty on a partial view throws an error when ListModel is the current Model
  • #30 - Pager url issues in category pages when blog is not root
  • #32 - Rss feed url for tag/category breaks when the tag/category contains a hyphen
  • #39 - Update shazwazza theme to reflect shazwazza.com (feature)
  • #48 - Category/Tag list in Vapor and Shazwazza themes order posts ascending instead of descending
  • #41 - Articulate Pager and Search Results
  • #12 - Articulate MetaWeblog route and Contour
  • #42 - Package restore doesn't work
  • #38 - Routes need to be rebuilt when articulate root node url names are changed or when articulate root nodes are added
  • #37 - UrlHelperExtensions methods for categories/tags/search do not respect the configured values for these url names
  • #34 - Surface Controllers on Pages Using VirtualRouteHandler Don't Fire
  • #36 - Multiple articulate roots without domains assigned causes YSOD with routing

The GitHub release page is up and has the details and the package available for download: https://github.com/Shazwazza/Articulate/releases/tag/v1.0.5.1

The Our release page is also up with the package available for download: http://our.umbraco.org/projects/starter-kits/articulate

More good news

I’m sure you are already aware of this but if not it’s worth mentioning that Umbraco 7.2 has been released!! If you haven’t seen the details, it’s a huge and exciting release, full details are on the Umbraco blog

And Articulate 1.0.5 is compatible with Umbraco 7.2, happy days! :)

Articulate 1.0.4 released

October 10, 2014 06:18

I’ve finally got around to releasing Articulate 1.0.4 today. Want to say a big thanks to all those who submitted pull requests, you guys rock! There’s a few nice fixes in this release but most importantly it fixes the issues with multi-tenancy when domains are assigned in Umbraco.

Here’s the release notes on GitHub with links to each issue fixed:

https://github.com/Shandem/Articulate/releases/tag/1.0.4

You can download the Umbraco package from there or from Our here:

http://our.umbraco.org/projects/starter-kits/articulate

Unfortunately I haven’t got around to getting this on Nuget yet – That’s because it has it’s own challenges since I’d like to perform a full Umbraco data install via Nuget… coming soon I hope :)

Enjoy!

This blog now powered by Articulate

June 26, 2014 04:14

I’ve recently decided to build a new open source blog engine powered by Umbraco called Articulate. There’s a few reasons why i wanted to do this:

  • Since my full time job is an Umbraco core developer, I spend most of my time building Umbraco and get very little time for using Umbraco. I wanted to change this dilemma and really use Umbraco and utilize many of the features we’ve been creating and try to push some of it’s boundaries. For me this is a perfect way to find inspiration for new Umbraco features and enhancements.
  • I’ve wanted to move my blog away from BlogEngine.Net to Umbraco for quite some time (dogfooding) but I really needed to have every feature that I use in BlogEngine.Net available
  • I wanted to make the blog experience as simple as possible in Umbraco
  • I wanted to be able to write blog posts directly from my mobile phone easily using the web

I’ve got some documentation written and I’ll keep updating this over time but hopefully there’s enough there to get you started. Since Articulate is open source and hosted on GitHub, any community contributions are hugely welcomed :) Whether that’s core code additions, fixes, documentation, etc… any contribution is a big help.

Articulate templates are based on themes and I think it would be super awesome if people started creating their own themes and releasing them as their own packages or including them in the Articulate core for release. Creating themes is really easy and in fact a few of the themes included with Articulate are open source MIT licensed themes migrated over from the Ghost blogging platform (which is also very easy to do).

The first version of Articulate is out and can be downloaded either from the Umbraco package repository or from GitHub. There are a few minor bugs in this release that have been reported and fixed and I’ll have a newer version out this week.