Mandaris Moore

I'm continuing to use Micro.blog as my blogging platform of choice. It's been very solid and I haven't had a night were I accidentally delete my working environment and have to put it together from scratch.

Although, I do miss messing around with different settings, the feeling that my words are actually being seen by other people makes up for it and the knowledge that if I want to export everything I can.

I'm still working on the flow of idea to final draft of longer works, but I think that's more because of how I haven't nailed what I want to create versus anything else.

The first thing I did with this site this year other that work on a plugin that I'm not ready to release to the world is update the meta data. I don't know if you - the reader- will see a difference but I'm pretty proud of what I did.

The next thing is to update all the catefory tags to make them more consistent.

Two puzzle pieces coming together via pexels.com

The more that I dive into the quest of having my own spot on the internet, the more that I find that I have things that I want to do with it. Which means more research, experiments and late nights.

Currently, I'm on a mission to get webmentions and pingback working on my site. It's been pretty slow going because I want to incorporate it into my current blogging workflow. A workflow that is currently not flowing at all1.

Anyway, I thought I'd focus on making some changes so that I can make it fit better with all the new stuff that is coming out for the indieweb.

Setting up sign in

The first thing to do is make some changes to my template to allow for sign up according to the web directions

I thought the easiest ways of doing this was to use github2 or twitter3. I pushed the github login near the top of the page so that it would look for it first.

{% if GITHUB_USERNAME %}
<!-- IndieWeb sign-in -->
<link rel="me" href="https://github.com/{{ GITHUB_USERNAME}}" />
{% endif %}

I then included the twitter login information with the rest of the twitter information.

{% if TWITTER_USERNAME %}
<!-- Twitter Specific Info -->
<meta name="twitter:site" content="@{{ TWITTER_USERNAME }}" />
<meta name="twitter:creator" content="@{{ TWITTER_USERNAME }}" />
<meta name="twitter:card" content="summary_large_image" />
<link rel="me" href="https://twitter.com/{{ TWITTER_USERNAME}}" />
{% endif %}

Setting up webmentions

After the login was set up, I added this to enable webmentions that are specific to any website that uses the template.

{% if WEBMENTIONS %}
<!-- Enabling webmention functionality -->
<link rel="pingback" href="https://webmention.io/{{ WEBMENTIONS }}/xmlrpc" />
<link rel="webmention" href="https://webmention.io/{{ WEBMENTIONS }}/webmention" />
{% endif %}

Unfortunately, I still need to test it and get it in front of other people to use. I'm going to lay the foundation down and do some research so that I can get ping backs to work properly.

More meta data

From my reading of indieweb.org, I see that it doesn't use the OpenGraph and Schema.org that I put in the theme.

I'm hesitant to add these new tags because it lowers the validation scores, but I hope that it will help with accessibility and just make the site work better for those who want to find it.

Conclusion

I've got a lot of things on my mind and places where I can make the site move forward. I hope that those who read this feel inspired and have some input on how to make the template better.

If so, the theme can be found here.

  1. I've got three places that I can sit down and make a blog post. My iPhone, my iMac, and my laptop. Currently, my favorite is my laptop but I don't take it everywhere or use it as much. My mind is having trouble just feeling comfortable writing recently. Add the complication of where the files should be saved and how to update previous posts and I start feeling like throwing my hands up. ↩

  2. Which was just bought by Microsoft a couple month ago. I don't know if it's the new Microsoft which is pro open source. ↩

  3. A dumpster fire of deplorables. ↩

Geometry picture by pixabay.

Table of Contents

Previously, I had written about how I found a solution to my compulsion to make sure that the headers on my blog were on the write2 level here.

As with so many other things in life, there was an easier1 solution that was built into python-markdown.

When I had first explored this issue, I had looked at the HeaderID it was marked as being deprecated and to be used for adding anchors for headings. I didn't read the whole thing because it didn't seem it would fit my needs. I continued on and found my current solution.

But, the thought that there could be a better way kept on nagging me even though I was happy3 with how my site turned out.

As I was in the process of updating my Pelican Test Content, I went back to the python-markdown extensions page to make sure that I had covered most of the use cases. I noticed that it had a Table of Contents.

All about that base

The first thing that I found was that the extension allows me to set the base for headers fairly easily by setting a property in my pelicanconfig.py. 

# Markdown options
MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'markdown.extensions.toc': {'baselevel': '3', 'title': 'Table of Contents'},
    },
    'output_format': 'html5',
}

This eliminates the need for the additional plugin and as an added bonus allows me to have a table of contents for those really long posts that I never write.

Table of Pain

The html that is generated is hard to read. There are only a couple mild things that I don't really enjoy about this new solution.

Div-ided we stand on syntax

  • I'd love if this wasn't in a div and used either a nav or aside tag for accessibility and my own personal comfort.
  • Also, the number of li and ul tags can be hard to read if you want to read the raw html.
  • Titles for table of contents is in a span tag. I find that kind of ironic.

Seriously, just nitpicky at this point.

Making it look nice

This part is just me going back to trying to figure out how to make it look nice in the browser. I imagine that it won't take long, but there are going to be a couple of ugly iterations.

  1. Easier being defined as having less dependencies. ↩

  2. Get it? :P ↩

  3. Mostly happy. ↩

In my last post, I left off with a list of things that I wanted to work on for the next release of the design of the blog. I'm still changing the header at the top of the page and I've been working on improving the contrast of the colors you see for links to make it easier to read. Something you can't spot just by looking is the fact that <h1> - <h3> tags don't correspond to the breakdown of the syntax of the rest of the site.

A small sample of the code that was being generated.

What do I see on the internet

I feel that a lot of the sites that are on the internet only use the <h1>, <h2>, <h3> tags and looking at some of the templates that I've come across for pelican use css classes to differentiate them in the design.

I don't have a problem with that, but I felt that it doesn't help those that might be using some kind of screen reader or parsing system1.

Searching for a solution

Once again, I started looking for a place where this had already been fixed and quickly found one that would make sure that the html that python-markdown would give me would match what I was expecting to give to my template.

Christian Prieto had already come up with this handy solution in 2016 and had put some tests and an example of how to incorporate it into pelican.

But there are further complications

Unfortunately, pelican has changed since the original and I wasn't able to get the solution to work. The readme says to add the following:

MD_EXTENSIONS = ['downheader']

But the latest documentation found here, have the markdown default to be defined as a dictionary and not an array2. The simplest way to get it to work is to change your pelicanconfig.py to have the following code.

# Markdown Plugins
MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'downheader': {},
    },
    'output_format': 'html5',
}

For me, I had to specify a value because the title of my site is in a <h1> tag and the article headers are in <h2>.

# Markdown Plugins
MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'downheader': {'levels': '2'},
    },
    'output_format': 'html5',
}

I've since made a pull request so that others can get around this as well.

Conclusion

I'm happier and happier with the way that the site is coming together, but I'm afraid of the amount of technical debt that the site is accruing as I go along. I've to to make the readme a priority for those who come after me and want to make this design better.

I've also taken some time to just take the header and just make a standalone project that demonstrates how it works. I points to the simple theme that comes with pelican so people can just download it after installing pelican, python-markdown and the mdx_downheader package.

  1. From what I've seen a lot of webcrawlers use the headers of a page to determine whether a site was worth putting in search results. ↩

  2. This isn't the only place that has this, but I've been having trouble just getting the projects that I am using up to date. Heck, my readme is one line at this point! ↩

I think I'm ready to mark my second pelican theme 1.0 as "Feature Complete" today! I started off with -what I thought- a simple premise of having a site site took a lot longer than I expected but I'm pretty happy with the site for now. But before I tag it and start working on 2.0, I want to go over what I've done so far.

Visualization of what I've accomplished with the blog.

Parsable

The first thing I started researching was how to make the site parsable by webcrawlers. Although it's a personal blog, I wanted people to be able to find the content easily.

OpenGraph

OpenGraph was the first thing that I came across and appealed to me the most because it's the preferred way of parsing data for Twitter1.

I found it especially rewarding that the tags are also parsed by facebook and my new favorite social network slack.

One of the technical difficulties that I ran into when adding OpenGraph tags was adding the images. The specification for OpenGraph states that images to be used need to be added as meta data in the head of the html. This can be a pain as the other data like title and date can be pulled from the article itself and I didn't want to go through all my old posts to add image meta data.

Luckily, the github user WhiskyEchoBravo had a project that searched the content of the post for images and added the first to the list of tags. I'm a little proud that I helped with issues with pages.

Afterwards, I did run into some frustration when the images that I added to posts wouldn't be as big as I expected.

Post in slack with a small image.

Ultimately, I think it's because of the mixing and matching of having OpenGraph and twitter specific tags and was solved it by making sure I used the following for my twitter card.

<meta name="twitter:card" content="summary_large_image" />

And now I get the post to unfurl nicely.

Post in slack with a large image.

Schema.org

This is the styling used by both Bing and Google. I put this in as a challenge to myself to make it work in both instances. I leaned a lot from the example on OrbitingWeb and refined what I was working with using another example that I found on github.

Valid Semantic Tags

For this, I just wanted to use some of those really cool semantic tags that html5 has given to us. When I look at the code for some pages on the internet I see a lot of <div> tags with classes that could be replaced with <main>, <nav>, or <section> tags.

I'm willing to just attribute it to my desire to have my own style or maybe just inexperience, but I'm happy to report that the site passes html validation except for the OpenGraph definitions found in the header.

figure it out

One technical hurdle I ran into was that I wanted my images to be wrapped in the <figure> tag and also have a <figcaption> tag that would have the alternative text.

I searched for a plugin for pelican2, but the closest thing I could find was liquid tags at the time3.

I did find jdittrich figureAltCaption project on github which was a extension for the python-markdown that pelican uses. I even submitted a pull request to allow it to do reference links!

There was a little confusion on getting it to work because pelican has been changing since some of these plugins were created.

Long story short, I had to add the following to my pelicanconfig.py to get it to work.

   # Markdown Plugins
MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'figureAltCaption':{},
    },
    'output_format': 'html5',
}

Easy to share

I wrote down that I wanted the site to be easy to share and it is when you look at the amount of tags and metadata that is in every page.

At one point, I wanted to add share buttons, but -with the rise in concerns about privacy- I wanted the users of the site to be the ones who would share it.

Also, I'm still working on color schemes so the buttons might clash with whatever I end up with.

Clash of the social buttons!

Accessible

One of the underlining principles of this site design is that I wanted it to be accessible to as many people as possible. It's part of the reason that I've worked so hard on making sure that I included so many semantic tags. I didn't think that this was particularly hard to do when you understand what needs to happen before you begin.

The theme doesn't have any errors at this point, but does loose some points because of the way that markdown headers are handled and the fact that I picked a low contrast color for my links. I'll fix it soon.

Conclusion and where I'm going next

Overall, I'm happy with this version of the site and blogging about it has helped me think about what places I want to refine going forward.

List of things to improve

  • Create a decent readme with all the packages and properties that the theme uses
  • Improve color contrast for reading
  • Add Cristian Prieto's mdx_downheader
  • Make the top navigation a little less clunky
  • Look into how to integrate micro.blog posts

If you want to contribute you can find the theme on github here.

  1. Twitter is still my social network of choice and -despite it's flaws- is not as creepy as facebook. ↩

  2. Seriously didn't see Chris MacMackin's figure-ref until I was writing this article. I'll have to look into it for my next version. ↩

  3. I used this to make my previous theme Tufte and did not want to go down that road twice. It is very specific to pelican and I didn't want to dive into more regular expressions when I knew there had to be a solution already created. ↩

A man in a gear. A cog in the machine of life.

I spent a little time with Pixelmator last night and found it to be fairly easy to make something like this. I thought it would take a while to make something would meet my needs.

I guess it shows that you never know what you can do until you try.

The only thing that I regret is that I went down the rabit hole and spent almost an hour this morning researching formats and dimensions for making my icon perfect.

Here are my resources if you want to find out more:

  • http://icoconvert.com/
  • https://stackoverflow.com/questions/1526747/ideal-size-for-ico
  • https://github.com/audreyr/favicon-cheat-sheet
  • https://mathiasbynens.be/notes/touch-icons

Example of markdown syntax meant to test new themes.

When I'm trying to come up with a new theme for my blog, I like to think about the different scenerios of what I can put together. I admit that a lot of what I design is rarely shown in my daily writing, but I like the possibilities of expressing myself in this way and part of me hopes that someone else will see my theme and use it or make it better.

In light of this, I don't like using my own content sometimes because I don't always have something recent to test with a theme with.

That's why I took some time and created a repo just for this purpose. I present:

Pelican Test Content!

It's a couple of articles and pages that I use to simulate a website in pelican. It looks like most of the theme designers create their own set of test data but I'm hoping that this can be the seed or at least add on to whatever else is available.

Writing this post in Byword

I like writing. I find it very relaxing and it allows me to get my thoughts together. Recently, I've gotten out of the habit of writing on a regular basis so I'm going to take this as an opportunity to start journaling again in the month of May.

I'll set a goal to start the day with a little bit of yoga followed by some writing on what I want to do with the day. Maybe some introspection as well.

If I had it my way, I'd put this all into DayOne, but it has been kind of stressful having it there where I don't have any control over when it goes away.

An example diagram created with PlantUML.

I'm going to be changing the pelican posts that I have that use the PlantUML plugin to be in the draft status.

I really enjoy having a way to put my words into a diagram, but I honestly haven't had a need to and having my computer pause for a second as it starts up java to render the diagrams everytime has gotten a little annoying.

Going forward, I'll use an application to create the diagrams and then just add them to my images directory.