[fastpages] GitHub Pages Blog Using Nbdev

nok · February 22, 2020, 9:58am

Thank! love this tool a lot, it make the blogging experience more seamlessly that I can just write in notebook and commit without worrying how to convert it to markdown later.

One small opinion about the page, it would be great if in the index page it could show more than just the blog title, I am thinking of also showing the summary from the notebook and optionally with images.

Another thing, I would like to change is the style/theme for the code block, I found the dark theme does not look very nice with a white background.

herchu · February 22, 2020, 5:03pm

I had tried different Github Pages themes but the rest of the supported ones didn’t work as I expected. It’s probably due to my lack of knowledge in jekyll&co. Also note that I tested them within the original fastpages template.

hamelsmu · February 22, 2020, 6:01pm

Changing themes is not supported because there are too many opportunities for CSS collisions. fastpages is a very opinionated platform with the trade off of making it easy for you.

Re: syntax highlighting that is something you can customize via CSS yourself if you so choose but is not something I plan on working on anytime soon. PRs are welcome on this, however.

Edit: you can use your own theme if you have enough knowledge of Jekyll and GitHub Actions, but it requires some work for each person. I think we would take a blog submission for someone who wants to go through this adventure and document their journey!

hamelsmu · February 22, 2020, 6:17pm

@nok I don’t know about putting picture previews, I’ll leave that up to the user to customize that. I do agree that having a summary under the title is probably necessary.

Added the below feature via https://github.com/fastai/fastpages/pull/95

You will have to copy all of your posts over if you want to upgrade.

nok · February 23, 2020, 1:30am

Thank you. Do I have to recreate from fastpages and copy my notes over? Since the first PR will modify the repo quite a bit, I am not sure how to pull the changes to upgrade

jeremy · February 23, 2020, 1:43am

Remind me: does fastpages support creating twitter cards for posts? We have that in fast.ai, but I don’t recall if it was copied over to fastpages. (If not, it probably should be, because it’s handy!)

The reason I mention it here is because it uses a special key image in the frontmatter, which could also be used in a post summary I guess.

hamelsmu · February 23, 2020, 1:49am

Hi @nok the way I would do it ( we will try to automate this at some point but bear with us):

create a new repo from the template
merge the PR etc. from the new repo
copy all your posts over manually, add, commit and push them to master.

Hope that helps

hamelsmu · February 23, 2020, 1:51am

@jeremy

Yes fastpages has the jekyll-seo-tag plugin (I believe it comes with minima) that supports the image and description front matter. I haven’t tested the image part of it but the description works.

I can add this to my backlog to test and verify that this works

Edit image previews in twitter work via the image: front matter

However, at the moment doesn’t seem to:

support remote urls
you can only reference images in assets/ or images/
this is one of those cumbersome situations if you reference your image locally to the notebooks folder, it will not work.

@jeremy How are you doing it now? Is this the same thing you are doing?

hamelsmu · February 23, 2020, 1:55am

That’s an interesting idea of using twitter card summaries as previews on the home page I haven’t thought of that. I Will look into this!

jeremy · February 23, 2020, 4:06am

Embarrassingly, I didn’t know about that plugin, so I added this to the template head layout:

  <meta name="twitter:site"    content="@{{ site.twitter_username }}">
  <meta name="twitter:creator" content="@{{ page.author }}">
  <meta name="twitter:title"   content="{{ page.title }}">
  {% if page.summary %}
  <meta name="twitter:description" content="{{ page.summary }}">
  {% else %}
  <meta name="twitter:description" content="{{ site.description }}">
  {% endif %}
  {% if page.image %}
  <meta name="twitter:card"  content="summary_large_image">
  <meta name="twitter:image" content="{{ site.url }}{{ page.image }}">
  {% else %}
  {% endif %}

Since it uses summary, it works with the usual nbdev summary. Although if description is more common, it’s possible nbdev should set that metadata too…

jeremy · February 23, 2020, 4:06am

BTW this is a great tool for testing cards: https://cards-dev.twitter.com/validator

hamelsmu · February 23, 2020, 4:33am

I was looking for the card validator for hours! Thank you for sharing that

hamelsmu · February 23, 2020, 4:35am

@jeremy @nok

Good news the image preview on the homepage feature has now been enabled on fastpages via https://github.com/fastai/fastpages/pull/104

Usage

You can enable this option by setting

show_image: true

in /_config.yml , it is set to false by default.

hamelsmu · February 23, 2020, 4:39am

@jeremy BTW I’m doing this in my template to alias the summary in nbdev to description for this exact reason

github.com

fastai/fastpages/blob/master/_action_files/fastpages.tpl#L7


{%- extends 'hide.tpl' -%}
{%- block body -%}
{%- set internals = ["metadata", "output_extension", "inlining", 
                    "raw_mimetypes", "global_content_filter"] -%}
---
{%- for k in resources |reject("in", internals) %}
{% if k == "summary" and "description" not in resources %}description{% else %}{{ k }}{% endif %}: {{ resources[k] |replace(':', '') }}
{%- endfor %}
layout: notebook
---


<!--
#################################################
### THIS FILE WAS AUTOGENERATED! DO NOT EDIT! ###
#################################################
# file to edit: {{ resources.nb_path }}
-->

{% if k == "summary" and "description" not in resources %}description{% else %}{{ k }}{% endif %}: {{ resources[k] |replace(':', '') }}

Not sure if its too hacky or not. Just sharing. I guess it makes notebooks and markdown behave a bit differently. I will put this on the list of things I have to document for users.

hamelsmu · February 23, 2020, 4:46am

Yeah now that I think about, it might be best if nbdev set this metadata, it would align all the things. cc: @Sylvain - we are thinking that summary in nbdev (you know that gets set with > in the front matter, perhaps should be renamed to description in order to also flow naturally into the various SEO plugins out there.

jeremy · February 23, 2020, 4:52am

I think you mean: cc @sgugger

hamelsmu · February 23, 2020, 7:48am

Another update. I thought the image preview was a bit ugly so I made it much more appealing. I encapsulated the image + post metadata in cards. Feature was added via https://github.com/fastai/fastpages/pull/107

This is still off by default. I wonder if I should turn it on by default. My feeling is I need to figure out pagination before turning this on by default, as the images can take up quite a bit of space.

EDIT, by default the site still looks like this (when the option is turned off and there are no images, I feel like cards are overkill)

What are your thoughts @jeremy @nok

sgugger · February 23, 2020, 5:28pm

I have just made a test and setting description instead of summary does not work for our exported docs, so the renaming in general is not possible.

jeremy · February 23, 2020, 5:46pm

Might be possible to set both bits of metadata?

jeremy · February 23, 2020, 5:46pm

I’d lean towards off by default.