I have one question.
What is the styling guideline?
The post from Jupyter notebook and Word will be reformatted into Markdown format.
Strictly speaking, this is not a pure markdown format since it has HTML tags in it.
Is there a guideline to add more of HTML thing? like how simple it should be?
I believe we could do so many things with it, but it will get much more complicated like including embedded javascript lines of code.
The only guideline I can think of right now is if you want to add HTML you follow this convention:
use the > key: value markdown convention for adding markup that will get turned into {% include <key>.html content=<value> %}, which means you will have to add key.html in _includes/ in the repo.
All of your html should be encapsulated within includes/<key>.html that way it is modular and can be easily edited or temporarily removed.
Is there anything you can think of adding? Some things that would be cool that requires javascript (maybe):
etc.
Thank you so much for pushing this forward, @hamelsmu! Impressed with how much youāve implemented in just a couple weeks.
While I was off, I had some time to think, and hereās what I think would be a good plan to get me back to speed. Please guide me and nudge me to work on the areas that you think make most sense.
fastpages to be a nbdev projectIf we checkout nbdev_template and implement everything thatās currently in _action_files as nbdev-driven code, weāll have:
fastpages_build instead of python nb2post.py
settings.ini.fastpages itself will be automatically tested in the lib notebooks, i.e. unit / integration tests for free.And the best part, itās easy to do ā maybe an hour or two, and I would be happy to do it ā that way I can re-read all the code and get up to speed.
Cons:
fastpages is under active development, unless I can make this change overnight and yo can review it, we risk having merge conflicts. Iām OK with a risk, and willing to keep up with the development pace.fastpages becomes an nbdev-based lib, it canāt be a github repo template anymore, weāll have to create a repo that templates the blog based of fastpages, which might become a bit an overkill (?), and maybe we can just do everything we want as a part of nbdev.After thinking about this, I want to discuss this more with you, @hamelsmu, Iām not sure whatās the best approach, maybe I should spend more time putting together a proposal before writing any code.
I havenāt ran the Docker-backed devtools yet, and I think itās a great idea to use a docker image and not have users install all the deps if they donāt want to!
On a Python-level, we can add a watcher that would watch for updates in Word documents and Notebooks, and rebuild the site preview locally on change.
This will make sure that the notebooks run correctly and the posts are reproducible, with a caveat that the posts have to be able to run on CPUs only. If the fastpages itself will be engineered with nbdev, and if the site itself will be a nbdev library, like I did in my blog (just drop another settings.ini in there), then itās as easy as nbdev_test_nbs.
We can document that behavior and guide users on how to make sure their notebooks run on CPU. Specifically, we can provide functions in fastpages that check whether itās running in a guthub action, or if a GPU is available, and based on that do something else in the notebook (i.e. donāt run the training loop, just grab saved weights from somewhere).
Note: alternative approach to conditional execution in nbdev_test_nbs would be to add a command to nbdev itself:
#skiptest
# don't run this cell in `nbdev_test_nbs`.
We can also store user credentials to a cloud of choice, say GCP, and make a github action that would spin up a spot GPU instance, and run all the notebooks (or just new / changed notebooks) on that instance! That way, users get full GPU CI on their research articles, guaranteeing reproducibility.
That CI might also report the metrics back, not just exit(0), i.e. plot a loss function and compare accuracy to a threshold value, provided in the pageās front matter metadata.
Iāll think more about whatās the best area for me to focus on, and implement a thing or two. I wonāt move forward with nbdev-backed lib thing before we discuss it, and Iāll try to write down more details about it.
The thing Iāll start with is Iāll move my blog to the updated fastpages and play around with it. If I feel like Iāll want to move things around, Iāll document these in PRs.
Hi @xnutsive ! Some things that could use some help at the moment:
Iām not sure about the idea of running actual code in the notebook inside Actions themselves (#3 and #4) , because Actions is a very resource-constrained envirnonment. The way to normally accomplish this is to use something like Kubernetes where you can define your infrastructure as code and deploy the notebook to get run there. However, I feel like that would be overkill and too complicated for most people ( I can barely figure out how to do all these things to be honest and it is a pain ).
As for making this an nbdev based project (#1) where we develop everything in nbdev, I am not sure about that either as there isnāt a great deal of python code (it is only used to drive the GitHub Actions), and it is difficult to test these Action scripts interactively in a notebook as they must be in Docker containers to emulate the GitHub Actions environment correctly (the idea is if you are going to test locally it should mirror the Actions environment).
That being said, I could be missing something or sometimes I can be dense. Please let me know if I have overlooked something. Also, given your involvement in this project, I would be happy to meet on hangouts or zoom (please DM me either here, twitter, etc) and we can talk real time as I feel like you have lots of good ideas in your head.
Thank you so much for these ideas, really appreciate it.
Helloļ¼My blog has been created based on the fastpage template. If the source code of the fastpage template is updated, how can I keep my blog updated?I am new to github.
Hi @jean1 you have to do this through git
git remote add upstream https://github.com/fastai/fastpages.git
git fetch upstream
git merge upstream/master
If you are using hub cli for GitHub I believe this command will work but havenāt tried that: https://hub.github.com/hub-sync.1.html
@hamelsmu, thank you fro the reply. I was wondering that too. Could we include it in the docsā¦
@hamelsmu For those three commands you just listed: The first two work fine. For the last one, I getā¦
$ git merge upstream/master
fatal: refusing to merge unrelated histories
This is for my repo created from your āclick hereā method of forking. What should we do when we get that error?
@drscotthawley try this https://www.educative.io/edpresso/the-fatal-refusing-to-merge-unrelated-histories-git-error
Ok @hamelsmu. so
$ git merge upstream/master --allow-unrelated-histories
warning: Cannot merge binary files: favicon.ico (HEAD vs. upstream/master)
Auto-merging index.md
CONFLICT (add/add): Merge conflict in index.md
Auto-merging favicon.ico
CONFLICT (add/add): Merge conflict in favicon.ico
Auto-merging assets/main.scss
CONFLICT (add/add): Merge conflict in assets/main.scss
Auto-merging about.md
CONFLICT (add/add): Merge conflict in about.md
Auto-merging _setup_pr_template.md
CONFLICT (add/add): Merge conflict in _setup_pr_template.md
Auto-merging _layouts/post.html
CONFLICT (add/add): Merge conflict in _layouts/post.html
Auto-merging _layouts/notebook.html
CONFLICT (add/add): Merge conflict in _layouts/notebook.html
Auto-merging _includes/head.html
CONFLICT (add/add): Merge conflict in _includes/head.html
Auto-merging _config.yml
CONFLICT (add/add): Merge conflict in _config.yml
Auto-merging _action_files/settings.ini
CONFLICT (add/add): Merge conflict in _action_files/settings.ini
Auto-merging _action_files/fastpages.tpl
CONFLICT (add/add): Merge conflict in _action_files/fastpages.tpl
Auto-merging _action_files/Dockerfile
CONFLICT (add/add): Merge conflict in _action_files/Dockerfile
Auto-merging README.md
CONFLICT (add/add): Merge conflict in README.md
Auto-merging .github/workflows/setup.yaml
CONFLICT (add/add): Merge conflict in .github/workflows/setup.yaml
Auto-merging .github/workflows/ci.yaml
CONFLICT (add/add): Merge conflict in .github/workflows/ci.yaml
Automatic merge failed; fix conflicts and then commit the result.
Whoaā¦ so many conflicts in files I never touched! Not sure if Iām going to succeed at keeping/replacing the right parts, but Iāll get started with viā¦
EDIT: Got it all done. Thanks.
My situation is the same as you. I wonder if this is caused by the difference between fork and template.Should we fork instead of creating through templates?
The best thing to do right now is to copy your blog posts (notebooks, word, markdown posts) to the a new repo you create from the new template. This is going to offer the easiest path at the moment
If you do significant customizations to your site the upgrade is going to be difficult, not sure there is a solution to that, yet.
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.
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.
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!
@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.
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
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.
Hi @nok the way I would do it ( we will try to automate this at some point but bear with us):
Hope that helps
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:
assets/ or images/
@jeremy How are you doing it now? Is this the same thing you are doing?