I noticed that I have been getting similar questions on the forums, as well as requests for help without proper information to allow me to troubleshoot. Therefore, I created this Troubleshooting Guide, which I will repost below for completeness:
Filing Bugs & Troubleshooting
These are required prerequisites before filing an issue on GitHub or on the fastai forums
Step 1: Search Relevant Places For Similar Issues
- [ ] Search the fastai forums for similar problems.
- [ ] Search issues on the fastpages repo for a similar problems?
- [ ] Read the README of the repo carefully
Step 2: Observe Build Logs When Developing Locally
- [ ] Run the fastpages blog server locally
- Pay attention to the emitted logs when you save your notebooks or files. Often, you will see errors here that will give you important clues.
- [ ] When developing locally, you will notice that Jupyter notebooks are converted to corresponding markdown files in the
_postsfolder. Take a look at the problematic blog posts and see if you can spot the offending HTML or markdown in that code.
- If you receive a Jekyll build error or a Liquid error, search for this error on Stack Overflow to provide more insight on the problem.
Step 3: See if there are errors in the build process of GitHub Actions.
- [ ] In your GitHub repository, you will have a tab called Actions. To find build errors, click on the
Eventdropdown list and select
push. Browse through tthe logs to see if you can find an error.
Step 4: Once you have performed all the above steps, post your issue in the fastai formus.
[ ] Use the nbdev & blogging category to specify your problem.
[ ] If you cannot find a similar issue create a new thread instead of commenting on an unrelated one.
When reporting a bug, provide this information:
- Steps to reproduce the problem
- A link to the notebook or markdown file where the error is occuring
- If the error is happening in GitHub Actions, a link to the specific error along with how you are able to reproduce this error. You must provide this in addition to the link to the notebook or markdown file.
- A screenshot / dump of relevant logs or error messages you are receiving from your local development environment. the local development server as indicated in the development guide.
You must provide ALL of the above information.
Malformed front matter. Note that anything defined in front matter must be valid YAML. Failure to provide valid YAML could result in your page not rendering in your blog. For example, if you want a colon in your title you must escape it with double quotes like this:
- title: "Deep learning: A tutorial"
or in a notebook
# "Deep learning: A tutorial"
See this tutorial on YAML for more information.
Colons, tilda, asteriks and other characters may cause your front matter to break and for your posts to not render. If you violoate these conventions you often get an error that looks something like this:
Error: YAML Exception reading ... (<unknown>): mapping values are not allowed
You are not able to customize the styling or theme of fastpages? A: See Customizing Fastpages
See the FAQ for frequently asked questions.