In the _config.yml file, the below is what I’ve typed. And I’ve searched for my id while inspecting the blog post web page and unfortunately I can’t find my id.
google_analytics: UA-XXXXXXXXX-X
That certainly looks correct - and works for me on github - locally it doesn’t show until you set jekyll environment to production. Are you trying this on github or locally?
JEKYLL_ENV=production bundle exec jekyll serve
Hmm I’m trying this on github. Are there any special settings that I’ll have to configure on the Google Analytics webpage?
Until it’s in your html header - that part doesn’t matter. Did you try locally with production set? Might give you a hint - and very hard to help you anymore without further knowledge.
Thanks Henrik, let me try locally to see if it works. For now I’m not able to see it in the html header.
Picking up on a Twitter thread, some comments around the “fastpages supports really easy Jupyter blogging” effusiveness on Twitter.
(Note this isn’t meant to be hostile, it’s meant to be usefully critical 
For any seasoned Github user and developer who’s also been responsible for maintaining documentation sites using Jekyll, fastpages “just” requires folk to use Github and Jekyll style publishing to publish a blog site from notebook files and markdown docs.
For anyone familiar with Github, git, and Jekyll publishing, the fastpages automation simplifies some of the faff required in getting that stuff working. (Other approaches, such as Jupyter Book, ipypublish and nbsphinx offer related publishing routes but less hype. A proper comparison of all the approaches might be useful…)
So if you’re familiar with Github and Jekyll, the benefits are quite possibly both clear and enticing. But if you aren’t a Github user or a Jekyll user, things are pretty much as opaque as every they were.
The fastpages mechanic of generating a PR on the first commit generated when cloning the template repo is really neat, and an idea I’ll likely steal. But for a novice, without mental model of how Github works, this doesn’t in and of itself make things that much easier. The naive user is faced with a complex UI, using complex jargon, and probably doesn’t know where to go looking for the PR, how to handle it, what it means when they do handle it, etc etc.
The file listing on the master home page you’re faced with when cloning the repo is also intimidating. There are a lot of files, there’s lots of directory names starting with scary underscores, lots of .whatever hidden files. That’s fine if you’re creating a workflow that’s “easy” for folk who are happy with all this stuff, but if the claim is that this is an “easy route into blogging with Jupyter” in general, it isn’t.
One of the attractive features of the Jupyter notebook UI and infrastructure is that someone with little technical knowledge on the command line can quickly start using magics and high level commands, a line at a time, to get stuff done. Just because someone can plot a chart a from a pandas data frame populate from a loaded in CSV file doesn’t necessarily mean they know how to set up the Jupyterhub server they’re actually a user of, nor even how to install pandas into the environment they’re using. As a user, why should they? The same goes for their familiarity, or otherwise, with Github and Jekyll. (By the by, it’s probably best to leave the “but they ought to…” arguments aside…)
I’m all for folk developing skills, but onboarding is really hard. And oftentimes, when trying to persuade people to adopt new tech in conservative institutions, you only get infrequent opportunities to entice them in. If you claim something is easy, that you “just” this and that, then watch their face as confusion and terror reigns, and you’ve lost your conversion opportunity. They won’t try again.
To make things really easy means taking things much slower. Cloning the repo and showing a clean page with a very simple set of instructions, and all the scary stuff hidden in branches, provides an opportunity for generating an easy way in. The initial readme could provide a set of very clear instructions about setting up tokens etc, along with why they’re necessary (eg Stephen Downes had a go at simplifying them here).
Things would also be simple if the all the Jekyll scaffolding were hidden away somewhere, and the user could just slowly introduce things into the top level directory, the homepage for their blog source files, with all the scaffolding hidden away and built on via branches.
This level of simplicity may or may not be desirable for a (semi-)professional, if ad hoc, tool, but if the desire is to find a way to make it easier for novices (to Github, to Jekyll) to publish in what is still quite a low level way, I think more scaffolding is required. (A limiting case of easy is probably to just click a button on your Jupyter notebook and have the file posted somewhere, from where it magically then appears on a public URL.)
Inspired by the initial commit handling Github Action, I started some baby steps explorations of a way of making “performative” Github commit actions (action-steps) that might (or might not!) make things simpler for a novice user (they also run the risk of them developing bad mental models, but I’m just exploring ideas).
For example, you might encourage someone via the readme to create a new file from the Github web UI with a particular filename or particular commit message, and then handle that in a particular way, perhaps updating the README with the next step; this might include some description of how you could then compare the original readme with the updated one. (I did start wondering whether I could code Adventure to be played via commit messages! Has that been done before I wonder?)
You might have additional commit messages that introduce new files into the top level repo, a file at a time. (Where to put simple documentation describing commit performative commands would be another issue!)
I appreciate this is probably not how Github is traditionally used, where a principle of least surprise about what appears in the repo compared to the files you actually commit is a sound one (that said, a lot of workflows do make use of commit hooks that do change files…) But I would argue that using Github for the primary purpose of making use of its Github Pages publishing mechanism is not using Github in a traditional version control application way either. Version control is NOT the aim. So what I’m thinking of here is where the user can instruct Git to add in very particular new files at particular times in response to particular commands issued via a particular commit message for a particular reason: to allow them to incrementally develop the complexity of their environment from within the environment as they grow familiar with it. Along the way, the mechanism could coach an introduce the user to features of Github that may be useful in a blogging context, such as the ability to “track changes” and maintain different versions of a content as you draft it etc. This would then introduce them to version control as a side effect of them developing particular blogging workflow practices in an environment that can coach them as they use it.
This may all just be nonsense, of course!
For some definition of “just”…
–tony
1 Like
Thanks @psychemedia for the constructive criticism. I wonder if some confusion can be mitigated by a
“Prerequisites Section” where I explain necessary prerequisite knowledge for fastpages is:
- Familiarity with GitHub, particularly pull requests, opening issues and resolving merge conflicts.
- Familiarity with markdown and Jupyter
- Optional, but incredibly helpful is basic familiarity with Jekyll which can be acquired by going through these docs: https://jekyllrb.com/docs/
What do you think? Would the above warning in the README prior to the setup steps mitigate these concerns and set proper expectations?
On another note I can clean up the repo a little to move some files into a folder away from view but there will still be some files there.
Yes and no. Yes it may clarify things, but no, it doesn’t really make it any easier. It just points at things and says “you should know this first”, “and this”. “And you have to bear in mind all these other things.” Whereas I suspect a machine could do a lot of that in the background?
I have this issue with colleagues in an edu setting. I think we should be making life easier for students, which means we might make it much harder for ourselves. Many of my colleagues disagree!
@psychemedia I agree with you at the moment isn’t something that is that is easy or intuitive for a newcomers to GitHub. The blogging functionality we built is bolted on top of the constraints and features of GitHub, whose central concern at the moment is version control, not publishing. This makes us force the user through several steps (SSH keys for example) that you would never dream of doing on a platform centered around blogging. Also the user interface /workflow is not completely optimized for blogging because of the same constraints.
I believe the new feature that this framework offers is Automation with GitHub Actions, that eliminate many tedious steps you would otherwise have to address if doing this manually ( including tons of edge cases for things like embedded images). Additionally fastpages is built on the nbdev project, which provides lots of additional features for notebook to HTML conversion for users.
If there are some obvious changes I can make to make the experience easier within what’s possible with GitHub today let me know. Also let me know if there is something else I should think about / consider. Thank you
Agreed… TINEWY (there is no easy way, yet…)!
Making use of Actions is a step forward, and the use of automated PRs is really interesting. As you say, co-opting Github as a blogging platform has many advantages, but also presents various obstacles and disadvantages. The workflows are also evolving, and it may be that as they evolve, some steps in current pipelines just disappear as pipeline stages themselves evolve.
Jupyter publishing workflows still lag Rmd workflows I think, and it’ll be interesting to see how fastpages, Jupyter Book etc play out, as well as what other publishing workflows emerge eg driven by things like Jupytext and nbdev.
If I come up with any potential simplifications, I’ll share them along:-)
1 Like
Looking around some old repos, I had a recipe here where I started trying to simplify some of the Jupyter Book publishing messiness, which also uses Jekyll, albeit usingCircleCI rather than Github Actions.
@hamelsmu I’d be careful of not stating prerequisite knowledge that’s not really there. With a step-by-step tutorial, there’s really not much to know (e.g. you don’t need to understand PRs, if we just say for that one PR “click on the button that says…”). There are a lot of people who have told us they’ve been able to start blogging thanks for fastpages, who previously found it too complicated. So I wouldn’t want to turn people off by saying it needs lots of prior knowledge.
Instead, we should focus on documenting the steps needed to create and use the tool (and continue to automate and simplify where possible).
2 Likes
understood and agreed
I am attempting to set up a local environment to test some changes, is it possible to setup on Window(with docker maybe?). I am not sure what a MakeFile is, is this something only available in Linux?
(edited: I download Make for window and succesfully run the make command in Window, http://gnuwin32.sourceforge.net/packages/make.htm). For some reason VSCode doesn’t pick up make correctly with no response, I have to start a terminal and run it, an it seems to work fine!
It seems that notebook file is not shown here for some reason. I can only see markdown post.
(edited: standard_init_linux.go:211: exec user process caused "no such file or directory, I found the fastpages_converter_1 and fastpages_fastpages_1 docker have this error )
I agree that you don’t want to put people off by saying they need all sorts of requisite knowledge, but you also have an opportunity to point to out to them in situ what the button they are pressing does and where they can learn more about it?
In passing, I note this sphinx-action uses this github-push-action which appears to use the GITHUB_TOKEN to push into the gh-pages branch? (Not tried it yet.)
This got to be my most tiny PR (spend almost 3 hours though), the problem is the CRLF(WINDOW) token and LF token(UNIX). Git would not even let me commit at all since Git does not pick up these changes. So I have to add/remove some line to let it commit.
Solve it by myself! I have no idea how I run into this Window/Linux error…But I feel great to fix this tiny bug. Learn about docker-compose up and docker-compose build at least,
which I have almost 0 idea what it is. (The build take so long that I was so nervous if the fix will work)
Please check and accept the PR if it looks fine (which literally does not change anything… on the surface)
2 Likes
Thx! I always amazed by the tools coming from fastai and I am happy to contribute by any means.
1 Like