41 | {%- else -%}
42 | {{ super() }}
43 | {%- endif -%}
44 | {% endblock output_area_prompt %}
--------------------------------------------------------------------------------
/_action_files/nb2post.py:
--------------------------------------------------------------------------------
1 | """Converts Jupyter Notebooks to Jekyll compliant blog posts"""
2 | from datetime import datetime
3 | import re, os, logging
4 | from nbdev import export2html
5 | from nbdev.export2html import Config, Path, _to_html, _re_block_notes
6 | from fast_template import rename_for_jekyll
7 |
8 | warnings = set()
9 |
10 | # Modify the naming process such that destination files get named properly for Jekyll _posts
11 | def _nb2htmlfname(nb_path, dest=None):
12 | fname = rename_for_jekyll(nb_path, warnings=warnings)
13 | if dest is None: dest = Config().doc_path
14 | return Path(dest)/fname
15 |
16 | # TODO: Open a GitHub Issue in addition to printing warnings
17 | for original, new in warnings:
18 | print(f'{original} has been renamed to {new} to be complaint with Jekyll naming conventions.\n')
19 |
20 | ## apply monkey patches
21 | export2html._nb2htmlfname = _nb2htmlfname
22 | export2html.notebook2html(fname='_notebooks/*.ipynb', dest='_posts/', template_file='/fastpages/fastpages.tpl', execute=False)
23 |
--------------------------------------------------------------------------------
/_action_files/parse_netlify.py:
--------------------------------------------------------------------------------
1 | import sys, re
2 | logs = sys.stdin.read()
3 |
4 | draft_url = re.findall(r'Website Draft URL: .*(https://.*)', logs)[0]
5 | assert draft_url, 'Was not able to find Draft URL in the logs:\n{}'.format(logs)
6 | print("::set-output name=draft_url::{}".format(draft_url))
7 |
8 |
--------------------------------------------------------------------------------
/_action_files/pr_comment.sh:
--------------------------------------------------------------------------------
1 | #!/bin/sh
2 |
3 | # Make a comment on a PR.
4 | # Usage:
5 | # > pr_comment.sh <>
6 |
7 | set -e
8 |
9 | # This is populated by our secret from the Workflow file.
10 | if [[ -z "${GITHUB_TOKEN}" ]]; then
11 | echo "Set the GITHUB_TOKEN env variable."
12 | exit 1
13 | fi
14 |
15 | if [[ -z "${ISSUE_NUMBER}" ]]; then
16 | echo "Set the ISSUE_NUMBER env variable."
17 | exit 1
18 | fi
19 |
20 | if [ -z "$1" ]
21 | then
22 | echo "No MESSAGE argument supplied. Usage: issue_comment.sh "
23 | exit 1
24 | fi
25 |
26 | MESSAGE=$1
27 |
28 | ## Set Vars
29 | URI=https://api.github.com
30 | API_VERSION=v3
31 | API_HEADER="Accept: application/vnd.github.${API_VERSION}+json"
32 | AUTH_HEADER="Authorization: token ${GITHUB_TOKEN}"
33 |
34 | # Create a comment with APIv3 # POST /repos/:owner/:repo/issues/:issue_number/comments
35 | curl -XPOST -sSL \
36 | -d "{\"body\": \"$MESSAGE\"}" \
37 | -H "${AUTH_HEADER}" \
38 | -H "${API_HEADER}" \
39 | "${URI}/repos/${GITHUB_REPOSITORY}/issues/${ISSUE_NUMBER}/comments"
40 |
--------------------------------------------------------------------------------
/_action_files/settings.ini:
--------------------------------------------------------------------------------
1 | [DEFAULT]
2 | lib_name = nbdev
3 | user = fastai
4 | branch = master
5 | version = 0.2.10
6 | description = Writing a library entirely in notebooks
7 | keywords = jupyter notebook
8 | author = Sylvain Gugger and Jeremy Howard
9 | author_email = info@fast.ai
10 | baseurl =
11 | title = nbdev
12 | copyright = fast.ai
13 | license = apache2
14 | status = 2
15 | min_python = 3.6
16 | audience = Developers
17 | language = English
18 | requirements = nbformat>=4.4.0 nbconvert>=5.6.1 pyyaml fastscript packaging
19 | console_scripts = nbdev_build_lib=nbdev.cli:nbdev_build_lib
20 | nbdev_update_lib=nbdev.cli:nbdev_update_lib
21 | nbdev_diff_nbs=nbdev.cli:nbdev_diff_nbs
22 | nbdev_test_nbs=nbdev.cli:nbdev_test_nbs
23 | nbdev_build_docs=nbdev.cli:nbdev_build_docs
24 | nbdev_nb2md=nbdev.cli:nbdev_nb2md
25 | nbdev_trust_nbs=nbdev.cli:nbdev_trust_nbs
26 | nbdev_clean_nbs=nbdev.clean:nbdev_clean_nbs
27 | nbdev_read_nbs=nbdev.cli:nbdev_read_nbs
28 | nbdev_fix_merge=nbdev.cli:nbdev_fix_merge
29 | nbdev_install_git_hooks=nbdev.cli:nbdev_install_git_hooks
30 | nbdev_bump_version=nbdev.cli:nbdev_bump_version
31 | nbdev_new=nbdev.cli:nbdev_new
32 | nbdev_detach=nbdev.cli:nbdev_detach
33 | nbs_path = nbs
34 | doc_path = images/copied_from_nb
35 | doc_host = https://nbdev.fast.ai
36 | doc_baseurl = %(baseurl)s/images/copied_from_nb/
37 | git_url = https://github.com/fastai/nbdev/tree/master/
38 | lib_path = nbdev
39 | tst_flags = fastai2
40 | custom_sidebar = False
41 | cell_spacing = 1
42 | monospace_docstrings = False
43 | jekyll_styles = note,warning,tip,important,youtube,twitter
44 |
45 |
--------------------------------------------------------------------------------
/_action_files/word2post.py:
--------------------------------------------------------------------------------
1 | import sys
2 | from pathlib import Path
3 | from fast_template import rename_for_jekyll
4 |
5 | if __name__ == '__main__':
6 | file_path = Path(sys.argv[1])
7 | new_name = rename_for_jekyll(file_path)
8 | print(new_name)
9 |
--------------------------------------------------------------------------------
/_action_files/word2post.sh:
--------------------------------------------------------------------------------
1 | #!/bin/sh
2 |
3 | # This sets the environment variable when testing locally and not in a GitHub Action
4 | if [ -z "$GITHUB_ACTIONS" ]; then
5 | GITHUB_WORKSPACE='/data'
6 | echo "=== Running Locally: All assets expected to be in the directory /data ==="
7 | fi
8 |
9 | # Loops through directory of *.docx files and converts to markdown
10 | # markdown files are saved in _posts, media assets are saved in assets/img//media
11 | for FILENAME in "${GITHUB_WORKSPACE}"/_word/*.docx; do
12 | [ -e "$FILENAME" ] || continue # skip when glob doesn't match
13 | NAME=${FILENAME##*/} # Get filename without the directory
14 | NEW_NAME=$(python3 "/fastpages/word2post.py" "${FILENAME}") # clean filename to be Jekyll compliant for posts
15 | BASE_NEW_NAME=${NEW_NAME%.md} # Strip the file extension
16 |
17 | if [ -z "$NEW_NAME" ]; then
18 | echo "Unable To Rename: ${FILENAME} to a Jekyll complaint filename for blog posts"
19 | exit 1
20 | fi
21 |
22 | echo "Converting: ${NAME} ---to--- ${NEW_NAME}"
23 | cd ${GITHUB_WORKSPACE} || { echo "Failed to change to Github workspace directory"; exit 1; }
24 | pandoc --from docx --to gfm --output "${GITHUB_WORKSPACE}/_posts/${NEW_NAME}" --columns 9999 \
25 | --extract-media="assets/img/${BASE_NEW_NAME}" --standalone "${FILENAME}"
26 |
27 | # Inject correction to image links in markdown
28 | sed -i.bak 's/!\[\](assets/!\[\]({{ site.url }}{{ site.baseurl }}\/assets/g' "_posts/${NEW_NAME}"
29 | # Remove intermediate files
30 | rm _posts/*.bak 2> /dev/null || true
31 |
32 | cat "${GITHUB_WORKSPACE}/_action_files/word_front_matter.txt" "_posts/${NEW_NAME}" > temp && mv temp "_posts/${NEW_NAME}"
33 | done
34 |
--------------------------------------------------------------------------------
/_action_files/word_front_matter.txt:
--------------------------------------------------------------------------------
1 | ---
2 | layout: post
3 | ---
4 |
--------------------------------------------------------------------------------
/_config.yml:
--------------------------------------------------------------------------------
1 | # Welcome to Jekyll!
2 | #
3 | # This config file is meant for settings that affect your whole blog.
4 | #
5 | # If you need help with YAML syntax, here are some quick references for you:
6 | # https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
7 | # https://learnxinyminutes.com/docs/yaml/
8 |
9 | title: OALABS Research
10 | description:
11 | github_username: OALabs
12 | # you can comment the below line out if your repo name is not different than your baseurl
13 | github_repo: "research"
14 |
15 | # OPTIONAL: override baseurl and url if using a custom domain
16 | # Note: leave out the trailing / from this value.
17 | url: "https://research.openanalysis.net" # the base hostname & protocol for your site, e.g. http://example.com
18 |
19 | ###########################################################
20 | ######### Special Instructions for baseurl ###############
21 | #
22 | #### Scenario One: If you do not have a Custom Domain #####
23 | # - if you are not using a custom domain, the baseurl *must* be set to your repo name
24 | #
25 | #### Scenario Two: If you have a Custom Domain #####
26 | # 1. If your domain does NOT have a subpath, this leave this value as ""
27 | # 2. If your domain does have a subpath, you must preceed the value with a / and NOT have a / at the end.
28 | # For example:
29 | # "" is valid
30 | # "/blog" is valid
31 | # "/blog/site/" is invalid ( / at the end)
32 | # "/blog/site" is valid
33 | # "blog/site" is invalid ( because doesn't begin with a /)
34 | #
35 | # 3. You must replace the parameter `baseurl` in _action_files/settings.ini with the same value as you set here but WITHOUT QUOTES.
36 | #
37 | baseurl: "" # the subpath of your site, e.g. "/blog".
38 |
39 | # Github and twitter are optional:
40 | minima:
41 | social_links:
42 |
43 |
44 | # Set this to true to get LaTeX math equation support
45 | use_math:
46 |
47 | # Set this to true to display the summary of your blog post under your title on the Home page.
48 | show_description: true
49 |
50 | # Set this to true to display image previews on home page, if they exist
51 | show_image: false
52 |
53 | # Set this to true to turn on annotations with hypothes.is (https://web.hypothes.is/)
54 | annotations: false
55 |
56 | # Set this to true to display tags on each post
57 | show_tags: true
58 |
59 | # Add your Google Analytics ID here if you have one and want to use it
60 | google_analytics:
61 |
62 | exclude:
63 | - docker-compose.yml
64 | - action.yml
65 | - Makefile
66 |
67 | # this setting allows you to keep pages organized in the _pages folder
68 | include:
69 | - _pages
70 |
71 | # This specifies what badges are turned on by default for notebook posts.
72 | default_badges:
73 | github: true
74 | binder: false
75 | colab: false
76 | deepnote: false
77 |
78 | # Escape HTML in post descriptions
79 | html_escape:
80 | description: false
81 |
82 | # Everything below here should be left alone. Modifications may break fastpages
83 | future: true
84 | theme: minima
85 | plugins:
86 | - jekyll-feed
87 | - jekyll-gist
88 | - jekyll-octicons
89 | - jekyll-toc
90 | - jekyll-twitter-plugin
91 | - jekyll-relative-links
92 | - jekyll-seo-tag
93 | - jekyll-remote-theme
94 | - jekyll-paginate
95 | - jekyll-sitemap
96 | - jemoji
97 |
98 | # See https://jekyllrb.com/docs/pagination/
99 | # For pagination to work, you cannot have index.md at the root of your repo, instead you must rename this file to index.html
100 | paginate: 15
101 | paginate_path: /page:num/
102 |
103 | remote_theme: jekyll/minima@69664442e5a45f631d5bccaba6d7978a91ce22c8
104 |
105 | titles_from_headings:
106 | enabled: true
107 | strip_title: true
108 | collections: true
109 |
110 | highlighter: rouge
111 | markdown: kramdown
112 | kramdown:
113 | math_engine: katex
114 | input: GFM
115 | auto_ids: true
116 | hard_wrap: false
117 | syntax_highlighter: rouge
118 |
119 | # to limit size of xml as it can grow quite large.
120 | feed:
121 | posts_limit: 5 #default posts_limit: 10
122 | excerpt_only: true
123 | disable: true
124 |
125 | exclude:
126 | - settings.ini
127 |
--------------------------------------------------------------------------------
/_fastpages_docs/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | _Adapted from [fastai/nbdev/CONTRIBUTING.md](https://github.com/fastai/nbdev/blob/master/CONTRIBUTING.md)_
2 |
3 | # How to contribute to fastpages
4 |
5 | First, thanks a lot for wanting to help! Some things to keep in mind:
6 |
7 | - The jupyter to blog post conversion functionality relies on [fastai/nbdev](https://github.com/fastai/nbdev). For idiosyncratic uses of nbdev that only apply to blogs that would require a large refactor to nbdev, it might be acceptable to apply a [monkey patch](https://stackoverflow.com/questions/5626193/what-is-monkey-patching) in `fastpages`. However, it is encouraged to contribute to `nbdev` where possible if there is a change that could unlock a new feature. If you are unsure, please open an issue in this repo to discuss.
8 |
9 |
10 | ## Note for new contributors from Jeremy
11 |
12 | It can be tempting to jump into a new project by questioning the stylistic decisions that have been made, such as naming, formatting, and so forth. This can be especially so for python programmers contributing to this project, which is unusual in following a number of conventions that are common in other programming communities, but not in Python. However, please don’t do this, for (amongst others) the following reasons:
13 |
14 | - Contributing to [Parkinson’s law of triviality](https://www.wikiwand.com/en/Law_of_triviality) has negative consequences for a project. Let’s focus on deep learning!
15 | - It’s exhausting to repeat the same discussion over and over again, especially when it’s been well documented already. When you have a question about the project, please check the pages in the docs website linked here.
16 | - You’re likely to get a warmer welcome from the community if you start out by contributing something that’s been requested on the forum, since you’ll be solving someone’s current problem.
17 | - If you start out by just telling us your point of view, rather than studying the background behind the decisions that have been made, you’re unlikely to be contributing anything new or useful.
18 | - I’ve been writing code for nearly 40 years now, across dozens of languages, and other folks involved have quite a bit of experience too - the approaches used are based on significant experience and research. Whilst there’s always room for improvement, it’s much more likely you’ll be making a positive contribution if you spend a few weeks studying and working within the current framework before suggesting wholesale changes.
19 |
20 |
21 | ## Did you find a bug?
22 |
23 | * Nobody is perfect, especially not us. But first, please double-check the bug doesn't come from something on your side. The [forum](http://forums.fast.ai/) is a tremendous source for help, and we'd advise to use it as a first step. Be sure to include as much code as you can so that other people can easily help you.
24 | * Then, ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/fastai/fastpages/issues).
25 | * If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/fastai/fastpages/issues/new). Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.
26 | * Be sure to add the complete error messages.
27 |
28 | #### Did you write a patch that fixes a bug?
29 |
30 | * Open a new GitHub pull request with the patch.
31 | * Ensure that your PR includes a test that fails without your patch, and pass with it.
32 | * Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
33 | * Before submitting, please be sure you abide by our [coding style](https://docs.fast.ai/dev/style.html) (where appropriate) and [the guide on abbreviations](https://docs.fast.ai/dev/abbr.html) and clean-up your code accordingly.
34 |
35 | ## Do you intend to add a new feature or change an existing one?
36 |
37 | * You can suggest your change on the [fastai forum](http://forums.fast.ai/) to see if others are interested or want to help.
38 | * Once your approach has been discussed and confirmed on the forum, you are welcome to push a PR, including a complete description of the new feature and an example of how it's used. Be sure to document your code in the notebook.
39 | * Ensure that your code includes tests that exercise not only your feature, but also any other code that might be impacted.
40 |
41 | ## PR submission guidelines
42 |
43 | Some general rules of thumb that will make your life easier.
44 |
45 | * Test locally before opening a pull request. See [the development guide](_fastpages_docs/DEVELOPMENT.md) for instructions on how to run fastpages on your local machine.
46 | * When you do open a pull request, please request a draft build of your PR by making a **comment with the magic command `/preview` in the pull request.** This will allow reviewers to see a live-preview of your changes without having to clone your branch.
47 | * You can do this multiple times, if necessary, to rebuild your preview due to changes. But please do not abuse this and test locally before doing this.
48 |
49 | * Keep each PR focused. While it's more convenient, do not combine several unrelated fixes together. Create as many branches as needing to keep each PR focused.
50 | * Do not mix style changes/fixes with "functional" changes. It's very difficult to review such PRs and it most likely get rejected.
51 | * Do not add/remove vertical whitespace. Preserve the original style of the file you edit as much as you can.
52 | * Do not turn an already submitted PR into your development playground. If after you submitted PR, you discovered that more work is needed - close the PR, do the required work and then submit a new PR. Otherwise each of your commits requires attention from maintainers of the project.
53 | * If, however, you submitted a PR and received a request for changes, you should proceed with commits inside that PR, so that the maintainer can see the incremental fixes and won't need to review the whole PR again. In the exception case where you realize it'll take many many commits to complete the requests, then it's probably best to close the PR, do the work and then submit it again. Use common sense where you'd choose one way over another.
54 | * When you open a pull request, you can generate a live preview build of how the blog site will look by making a comment in the PR that contains this command: `/preview`. GitHub will build your site and drop a temporary link for everyone to review. You can do this as multiple times if necessary, however, as mentioned previously do not turn an already submitted PR into a development playground.
55 |
56 | ## Do you have questions about the source code?
57 |
58 | * Please ask it on the [fastai forum](http://forums.fast.ai/) (after searching someone didn't ask the same one before with a quick search). We'd rather have the maximum of discussions there so that the largest number can benefit from it.
59 |
60 | ## Do you want to contribute to the documentation?
61 |
62 | * PRs are welcome for this. For any confusion about the documentation, please feel free to open an issue on this repo.
63 |
64 |
--------------------------------------------------------------------------------
/_fastpages_docs/DEVELOPMENT.md:
--------------------------------------------------------------------------------
1 | # Development Guide
2 | - [Seeing All Options From the Terminal](#seeing-all-commands-in-the-terminal)
3 | - [Basic usage: viewing your blog](#basic-usage-viewing-your-blog)
4 | - [Converting the pages locally](#converting-the-pages-locally)
5 | - [Visual Studio Code integration](#visual-studio-code-integration)
6 | - [Advanced usage](#advanced-usage)
7 | - [Rebuild all the containers](#rebuild-all-the-containers)
8 | - [Removing all the containers](#removing-all-the-containers)
9 | - [Attaching a shell to a container](#attaching-a-shell-to-a-container)
10 |
11 | You can run your fastpages blog on your local machine, and view any changes you make to your posts, including Jupyter Notebooks and Word documents, live.
12 | The live preview requires that you have Docker installed on your machine. [Follow the instructions on this page if you need to install Docker.](https://www.docker.com/products/docker-desktop)
13 |
14 | ## Seeing All Commands In The Terminal
15 |
16 | There are many different `docker-compose` commands that are necessary to manage the lifecycle of the fastpages Docker containers. To make this easier, we aliased common commands in a [Makefile](https://www.gnu.org/software/make/manual/html_node/Introduction.html).
17 |
18 | You can quickly see all available commands by running this command in the root of your repository:
19 |
20 | `make`
21 |
22 | ## Basic usage: viewing your blog
23 |
24 | All of the commands in this block assume that you're in your blog root directory.
25 | To run the blog with live preview:
26 |
27 | ```bash
28 | make server
29 | ```
30 |
31 | When you run this command for the first time, it'll build the required Docker images, and the process might take a couple minutes.
32 |
33 | This command will build all the necessary containers and run the following services:
34 | 1. A service that monitors any changes in `./_notebooks/*.ipynb/` and `./_word/*.docx;*.doc` and rebuild the blog on change.
35 | 2. A Jekyll server on https://127.0.0.1:4000 — use this to preview your blog.
36 |
37 | The services will output to your terminal. If you close the terminal or hit `Ctrl-C`, the services will stop.
38 | If you want to run the services in the background:
39 |
40 | ```bash
41 | # run all services in the background
42 | make server-detached
43 |
44 | # stop the services
45 | make stop
46 | ```
47 |
48 | If you need to restart just the Jekyll server, and it's running in the background — you can do `make restart-jekyll`.
49 |
50 | _Note that the blog won't autoreload on change, you'll have to refresh your browser manually._
51 |
52 | **If containers won't start**: try `make build` first, this would rebuild all the containers from scratch, This might fix the majority of update problems.
53 |
54 | ## Converting the pages locally
55 |
56 | If you just want to convert your notebooks and word documents to `.md` posts in `_posts`, this command will do it for you:
57 |
58 | ```bash
59 | make convert
60 | ```
61 |
62 | You can launch just the jekyll server with `make server`.
63 |
64 | ## Visual Studio Code integration
65 |
66 | If you're using VSCode with the Docker extension, you can run these containers from the sidebar: `fastpages_watcher_1` and `fastpages_jekyll_1`.
67 | The containers will only show up in the list after you run or build them for the first time. So if they're not in the list — try `make build` in the console.
68 |
69 | ## Advanced usage
70 |
71 | ### Rebuild all the containers
72 | If you changed files in `_action_files` directory, you might need to rebuild the containers manually, without cache.
73 |
74 | ```bash
75 | make build
76 | ```
77 |
78 | ### Removing all the containers
79 | Want to start from scratch and remove all the containers?
80 |
81 | ```
82 | make remove
83 | ```
84 |
85 | ### Attaching a shell to a container
86 | You can attach a terminal to a running service:
87 |
88 | ```bash
89 |
90 | # If the container is already running:
91 |
92 | # attach to a bash shell in the jekyll service
93 | make bash-jekyll
94 |
95 | # attach to a bash shell in the watcher service.
96 | make bash-nb
97 | ```
98 |
99 | _Note: you can use `docker-compose run` instead of `make bash-nb` or `make bash-jekyll` to start a service and then attach to it.
100 | Or you can run all your services in the background, `make server-detached`, and then use `make bash-nb` or `make bash-jekyll` as in the examples above._
101 |
102 |
--------------------------------------------------------------------------------
/_fastpages_docs/NOTEBOOK_FOOTNOTES.md:
--------------------------------------------------------------------------------
1 | # Detailed Guide To Footnotes in Notebooks
2 |
3 | Notebook -> HTML Footnotes don't work the same as Markdown. There isn't a good solution, so made these Jekyll plugins as a workaround
4 |
5 | ```
6 | This adds a linked superscript {% fn 15 %}
7 |
8 | {{ "This is the actual footnote" | fndetail: 15 }}
9 | ```
10 |
11 | 
12 |
13 | You can have links, but then you have to use **single quotes** to escape the link.
14 | ```
15 | This adds a linked superscript {% fn 20 %}
16 |
17 | {{ 'This is the actual footnote with a [link](www.github.com) as well!' | fndetail: 20 }}
18 | ```
19 | 
20 |
21 | However, what if you want a single quote in your footnote? There is not an easy way to escape that. Fortunately, you can use the special HTML character `'` (you must keep the semicolon!). For example, you can include a single quote like this:
22 |
23 |
24 | ```
25 | This adds a linked superscript {% fn 20 %}
26 |
27 | {{ 'This is the actual footnote; with a [link](www.github.com) as well! and a single quote ' too!' | fndetail: 20 }}
28 | ```
29 |
30 | 
31 |
--------------------------------------------------------------------------------
/_fastpages_docs/README_TEMPLATE.md:
--------------------------------------------------------------------------------
1 | [//]: # (This template replaces README.md when someone creates a new repo with the fastpages template.)
2 |
3 | 
4 | 
5 | [](https://github.com/fastai/fastpages)
6 |
7 | https://{_username_}.github.io/{_repo_name_}/
8 |
9 | # My Blog
10 |
11 |
12 | _powered by [fastpages](https://github.com/fastai/fastpages)_
13 |
14 |
15 | ## What To Do Next?
16 |
17 | Great! You have setup your repo. Now its time to start writing content. Some helpful links:
18 |
19 | - [Writing Blogs With Jupyter](https://github.com/fastai/fastpages#writing-blog-posts-with-jupyter)
20 |
21 | - [Writing Blogs With Markdown](https://github.com/fastai/fastpages#writing-blog-posts-with-markdown)
22 |
23 | - [Writing Blog Posts With Word](https://github.com/fastai/fastpages#writing-blog-posts-with-microsoft-word)
24 |
25 | - [(Optional) Preview Your Blog Locally](_fastpages_docs/DEVELOPMENT.md)
26 |
27 | Note: you may want to remove example blog posts from the `_posts`, `_notebooks` or `_word` folders (but leave them empty, don't delete these folders) if you don't want these blog posts to appear on your site.
28 |
29 | Please use the [nbdev & blogging channel](https://forums.fast.ai/c/fastai-users/nbdev/48) in the fastai forums for any questions or feature requests.
30 |
--------------------------------------------------------------------------------
/_fastpages_docs/TROUBLESHOOTING.md:
--------------------------------------------------------------------------------
1 | # Filing Bugs & Troubleshooting
2 |
3 | These are required prerequisites before filing an issue on GitHub or on the [fastai forums](https://forums.fast.ai/)
4 |
5 | ## Step 1: Attempt To Upgrade fastpages
6 |
7 | See the [Upgrading guide](https://github.com/fastai/fastpages/blob/master/_fastpages_docs/UPGRADE.md).
8 |
9 | **In addition to upgrading**, if developing locally, refresh your Docker containers with the following commands from the root of your repo:
10 |
11 | `make remove` followed by `make build`
12 |
13 | ## Step 2: Search Relevant Places For Similar Issues
14 |
15 | - [ ] Search the [fastai forums](https://forums.fast.ai/) for similar problems.
16 | - [ ] Search issues on the [fastpages repo](https://github.com/fastai/fastpages/) for a similar problems?
17 | - [ ] Read the [README of the repo](https://github.com/fastai/fastpages/blob/master/README.md) carefully
18 |
19 |
20 | ## Step 3: Observe Build Logs When Developing Locally
21 |
22 | - [ ] Run the [fastpages blog server locally](DEVELOPMENT.md)
23 | - 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.
24 | - [ ] When developing locally, you will notice that Jupyter notebooks are converted to corresponding markdown files in the `_posts` folder. Take a look at the problematic blog posts and see if you can spot the offending HTML or markdown in that code.
25 | - Use your browser's developer tools to see if there are any errors. Common errors are (1) not able to find images because they have not been saved into the right folder, (2) javascript or other errors.
26 | - 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.
27 |
28 | ## Step 4: See if there are errors in the build process of GitHub Actions.
29 |
30 | - [ ] In your GitHub repository, you will have a tab called **Actions**. To find build errors, click on the `Event` dropdown list and select `push`. Browse through tthe logs to see if you can find an error. If you receive an error, read the error message and try to debug.
31 |
32 | ## Step 5: Once you have performed all the above steps, post your issue in the fastai forums or a GitHub Issue.
33 |
34 | - [ ] Use the [nbdev & blogging category](https://forums.fast.ai/c/fastai-users/nbdev/48) to specify your problem if posting on the fastpages forums.
35 | - [ ] If you cannot find a similar issue create a new thread instead of commenting on an unrelated one.
36 | - When reporting a bug, provide this information:
37 |
38 | 1. Steps to reproduce the problem
39 | 2. **A link to the notebook or markdown file** where the error is occuring
40 | 3. 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**.
41 | 4. 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](https://github.com/fastai/fastpages/blob/master/_fastpages_docs/DEVELOPMENT.md).
42 |
43 |
44 | **You must provide ALL of the above information**.
45 |
46 | # Frequent Errors
47 |
48 | 1. 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:
49 |
50 | ` - title: "Deep learning: A tutorial"`
51 |
52 | or in a notebook
53 |
54 | `# "Deep learning: A tutorial"`
55 |
56 | See this [tutorial on YAML](https://rollout.io/blog/yaml-tutorial-everything-you-need-get-started/) for more information.
57 |
58 | **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:
59 |
60 | ```bash
61 | Error: YAML Exception reading ... (): mapping values are not allowed
62 | ```
63 |
64 | 2. Can you customize the styling or theme of fastpages? **A**: See [Customizing Fastpages](https://github.com/fastai/fastpages#customizing-fastpages)
65 |
66 | 3. Your initial build failed on GH-Pages Status
67 |
68 | `Error messsage: Unable to build page. Please try again later.` `Error: Process completed with exit code 1.`
69 |
70 | If your github username contains capital letters e.g. YourUserName, go to [config file](../_config.yml#L17) line 17 and rename `YourUserName.github.io` to `yourusername.github.io`. After the commit blog should build without error.
71 |
72 | See the [FAQ](https://github.com/fastai/fastpages#faq) for frequently asked questions.
73 |
--------------------------------------------------------------------------------
/_fastpages_docs/UPGRADE.md:
--------------------------------------------------------------------------------
1 | # Upgrading fastpages
2 |
3 |
4 |
5 | - [Automated Upgrade](#automated-upgrade)
6 | - [Step 1: Open An Issue With The Upgrade Template.](#step-1-open-an-issue-with-the-upgrade-template)
7 | - [Step 2: Click `Submit new issue`](#step-2-click-submit-new-issue)
8 | - [Step 3: A Link to Pull Request Will Appear](#step-3-a-link-to-pull-request-will-appear)
9 | - [Step 4: Review & Merge PR](#step-4-review-merge-pr)
10 | - [Manual Upgrade](#manual-upgrade)
11 | - [Easy Way (Recommended)](#easy-way-recommended)
12 | - [Advanced](#advanced)
13 | - [Additional Resources](#additional-resources)
14 |
15 |
16 |
17 | **For fastpages repos that are older than December 1st, 2020 the only way to upgrade is to create a brand-new fastpages repo and copy your blog post files into it.** This is because of breaking changes that were made to GitHub Actions around that time.
18 |
19 | There are two ways to upgrade fastpages. One is an automated way that assumes you have made no changes to the HTML of your site. Alternatively, you may [upgrade manually](#manual-upgrade) and determine which changes to accept or reject. For most people we recommend upgrading fastpages automatically.
20 |
21 | ## Automated Upgrade
22 |
23 | - This method is appropriate for those who have not customized the HTML of their site.
24 | - **If you are unsure, try the Automated approach and review which files are changed in the automated PR** to see if this appropriate for you.
25 |
26 | ### Step 1: Open An Issue With The Upgrade Template.
27 |
28 | - Open a new issue in your repository, and push the "Get Started" button for the `[fastpages] Automated Upgrade` Issue template, which looks like this:
29 | - **IF YOU DON'T SEE THIS**: you have an older version of fastpages and you **must [manually upgrade](#manual-upgrade) once** to get this new functionality.
30 |
31 | 
32 |
33 | ### Step 2: Click `Submit new issue`
34 |
35 | - Be careful not to change anything before clicking the button.
36 |
37 | 
38 |
39 | ### Step 3: A Link to Pull Request Will Appear
40 |
41 | - This issue will trigger GitHub to open a PR making changes to your repository for the upgrade to take palce. A comment with the link to the PR will be made in the issue, and will look like this:
42 |
43 | 
44 |
45 | It is possible that you might receive an error message instead of this command. You can follow the instructions in the comment to troubleshoot the issue. Common reasons for receiving an error are:
46 |
47 | - You are up to date, therefore no upgrade is possible. You will see an error that there is "nothing to commit".
48 | - You already have a PR from a previous upgrade open that you never merged.
49 |
50 | Please [ask on the forums](https://forums.fast.ai/) if you have encounter another problem that is unclear.
51 |
52 | ### Step 4: Review & Merge PR
53 |
54 | - Ensure that you read the instructions in the PR carefully. Furthermore, carefully review which files will be changed to determine if this interferes with any customizations you have mades to your site. When ready, select `Merge pull request`.
55 | - If the PR is making undesired changes to files you can use the manual upgrade approach instead.
56 |
57 | ## Manual Upgrade
58 |
59 | ### Easy Way (Recommended)
60 |
61 | Create a new repo with the current `fastpages` template by following the [setup instructions](https://github.com/fastai/fastpages#setup-instructions) in the README, and copy all of your blog posts from `_notebooks`, `_word`, and `_posts` into the new template. This is very similar to what the automated process is doing.
62 |
63 | ### Advanced
64 |
65 | - This method is appropriate for those who made customizations to the HTML of fastpages.
66 | - You must proceed with caution, as new versions of fastpages may not be compatible with your customizations.
67 | - You can use git to perform the upgrade by [following this approach](https://stackoverflow.com/questions/56577184/github-pull-changes-from-a-template-repository/56577320) instead. A step-by-step companion to this stack overflow post with screenshots is [written up here](https://github.com/fastai/fastpages/issues/163#issuecomment-593766189).
68 | - Be careful to not duplicate files, as files in fastpages have been reorganized several times.
69 |
70 |
71 | ## Additional Resources
72 |
73 | - [This Actions workflow](/.github/workflows/upgrade.yaml) defines the automated upgrade process.
74 | - You can get more help with upgrading in the [fastai forums - nbdev & blogging category](https://forums.fast.ai/c/fastai-users/nbdev/48).
75 |
--------------------------------------------------------------------------------
/_fastpages_docs/_checkbox.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/_checkbox.png
--------------------------------------------------------------------------------
/_fastpages_docs/_manual_setup.md:
--------------------------------------------------------------------------------
1 | # Manual Setup Instructions
2 |
3 | These are the setup steps that are automated by [setup.yaml](.github/workflows/setup.yaml)
4 |
5 | 1. Click the [](https://github.com/fastai/fastpages/generate) button to create a copy of this repo in your account.
6 |
7 | 2. [Follow these instructions to create an ssh-deploy key](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys). Make sure you **select Allow write access** when adding this key to your GitHub account.
8 |
9 | 3. [Follow these instructions to upload your deploy key](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets) as an encrypted secret on GitHub. Make sure you name your key `SSH_DEPLOY_KEY`. Note: The deploy key secret is your **private key** (NOT the public key).
10 |
11 | 4. [Create a branch](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository#creating-a-branch) named `gh-pages`.
12 |
13 | 5. Change the badges on this README to point to **your** repository instead of `fastai/fastpages`. Badges are organized in a section at the beginning of this README. For example, you should replace `fastai` and `fastpages` in the below url:
14 |
15 | ``
16 |
17 | to
18 |
19 | ``
20 |
21 | 6. Change `baseurl:` in `_config.yaml` to the name of your repository. For example, instead of
22 |
23 | `baseurl: "/fastpages"`
24 |
25 | this should be
26 |
27 | `baseurl: "/your-repo-name"`
28 |
29 | 7. Similarly, change the `url:` parameter in `_config.yaml` to the url your blog will be served on. For example, instead of
30 |
31 | `url: "https://fastpages.fast.ai/"`
32 |
33 | this should be
34 |
35 | `url: "https://.github.io"`
36 |
37 | 8. Read through `_config.yaml` carefully as there may be other options that must be set. The comments in this file will provide instructions.
38 |
39 | 9. Delete the `CNAME` file from the root of your `master` branch (or change it if you are using a custom domain)
40 |
41 | 10. Go to your [repository settings and enable GitHub Pages](https://help.github.com/en/enterprise/2.13/user/articles/configuring-a-publishing-source-for-github-pages) with the `gh-pages` branch you created earlier.
--------------------------------------------------------------------------------
/_fastpages_docs/_paginate.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/_paginate.png
--------------------------------------------------------------------------------
/_fastpages_docs/_post_tags.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/_post_tags.png
--------------------------------------------------------------------------------
/_fastpages_docs/_setup_pr_template.md:
--------------------------------------------------------------------------------
1 | Hello :wave: @OALabs! Thank you for using fastpages!
2 |
3 | ## Before you merge this PR
4 |
5 | 1. Create an ssh key-pair. Open this utility. Select: `RSA` and `4096` and leave `Passphrase` blank. Click the blue button `Generate-SSH-Keys`.
6 |
7 | 2. Navigate to this link and click `New repository secret`. Copy and paste the **Private Key** into the `Value` field. This includes the "---BEGIN RSA PRIVATE KEY---" and "--END RSA PRIVATE KEY---" portions. **In the `Name` field, name the secret `SSH_DEPLOY_KEY`.**
8 |
9 | 3. Navigate to this link and click the `Add deploy key` button. Paste your **Public Key** from step 1 into the `Key` box. In the `Title`, name the key anything you want, for example `fastpages-key`. Finally, **make sure you click the checkbox next to `Allow write access`** (pictured below), and click `Add key` to save the key.
10 |
11 | 
12 |
13 |
14 | ### What to Expect After Merging This PR
15 |
16 | - GitHub Actions will build your site, which will take 2-3 minutes to complete. **This will happen anytime you push changes to the master branch of your repository.** You can monitor the logs of this if you like on the [Actions tab of your repo](https://github.com/OALabs/research/actions).
17 | - Your GH-Pages Status badge on your README will eventually appear and be green, indicating your first successful build.
18 | - You can monitor the status of your site in the GitHub Pages section of your [repository settings](https://github.com/OALabs/research/settings).
19 |
20 | If you are not using a custom domain, your website will appear at:
21 |
22 | #### https://OALabs.github.io/research
23 |
24 |
25 | ## Optional: Using a Custom Domain
26 |
27 | 1. After merging this PR, add a file named `CNAME` at the root of your repo. For example, the `fastpages` blog is hosted at `https://fastpages.fast.ai`, which means [our CNAME](https://github.com/fastai/fastpages/blob/master/CNAME) contains the following contents:
28 |
29 |
30 | >`fastpages.fast.ai`
31 |
32 |
33 | 2. Change the `url` and `baseurl` parameters in your `/_config.yml` file to reflect your custom domain.
34 |
35 |
36 | Wondering how to setup a custom domain? See [this article](https://dev.to/trentyang/how-to-setup-google-domain-for-github-pages-1p58). You must add a CNAME file to the root of your master branch for the intructions in the article to work correctly.
37 |
38 |
39 | ## Questions
40 |
41 | Please use the [nbdev & blogging channel](https://forums.fast.ai/c/fastai-users/nbdev/48) in the fastai forums for any questions or feature requests.
42 |
--------------------------------------------------------------------------------
/_fastpages_docs/_show_image_true.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/_show_image_true.png
--------------------------------------------------------------------------------
/_fastpages_docs/_upgrade_pr.md:
--------------------------------------------------------------------------------
1 | Hello :wave: @{_username_}!
2 |
3 | This PR pulls the most recent files from [fastpages](https://github.com/fastai/fastpages), and attempts to replace relevant files in your repository, without changing the content of your blog posts. This allows you to receive bug fixes and feature updates.
4 |
5 | ## Warning
6 |
7 | If you have applied **customizations to the HTML or styling of your site, they may be lost if you merge this PR. Please review the changes this PR makes carefully before merging!.** However, for people who only write content and don't change the styling of their site, this method is recommended.
8 |
9 | If you would like more fine-grained control over what changes to accept or decline, consider [following this approach](https://stackoverflow.com/questions/56577184/github-pull-changes-from-a-template-repository/56577320) instead.
10 |
11 | ### What to Expect After Merging This PR
12 |
13 | - GitHub Actions will build your site, which will take 3-4 minutes to complete. **This will happen anytime you push changes to the master branch of your repository.** You can monitor the logs of this if you like on the [Actions tab of your repo](https://github.com/{_username_}/{_repo_name_}/actions).
14 | - You can monitor the status of your site in the GitHub Pages section of your [repository settings](https://github.com/{_username_}/{_repo_name_}/settings).
15 |
--------------------------------------------------------------------------------
/_fastpages_docs/annotate.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/annotate.png
--------------------------------------------------------------------------------
/_fastpages_docs/enable_actions.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/enable_actions.png
--------------------------------------------------------------------------------
/_fastpages_docs/fastapges-setup.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/fastapges-setup.gif
--------------------------------------------------------------------------------
/_fastpages_docs/highlight_dracula.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/highlight_dracula.png
--------------------------------------------------------------------------------
/_fastpages_docs/highlight_original.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/highlight_original.png
--------------------------------------------------------------------------------
/_fastpages_docs/upgrade_step1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/upgrade_step1.png
--------------------------------------------------------------------------------
/_fastpages_docs/upgrade_step2.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/upgrade_step2.png
--------------------------------------------------------------------------------
/_fastpages_docs/upgrade_step3.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/_fastpages_docs/upgrade_step3.png
--------------------------------------------------------------------------------
/_fastpages_docs/version.txt:
--------------------------------------------------------------------------------
1 | 2.1.48
2 |
--------------------------------------------------------------------------------
/_includes/alert.html:
--------------------------------------------------------------------------------
1 |
2 |
3 | Do not manually save images into this folder. This is used by GitHub Actions to automatically copy images. Any images you save into this folder could be deleted at build time.
--------------------------------------------------------------------------------
/images/diagram.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/images/diagram.png
--------------------------------------------------------------------------------
/images/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/images/favicon.ico
--------------------------------------------------------------------------------
/images/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/OALabs/research/d0a6daae41e7d9bc3b29930de2b6ce9baf1aa277/images/logo.png
--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
1 | ---
2 | layout: home
3 | search_exclude: true
4 | image: images/logo.png
5 | ---
6 |
7 | [](https://www.youtube.com/c/OALabs)
8 | [](https://www.twitch.tv/oalabslive)
9 | [](https://discord.gg/cw4U3WHvpn)
10 | [](https://www.patreon.com/oalabs)
11 |
12 | This is a collection of our raw research notes. Each post is generated from a [Jupyter Notebook](https://jupyter.org/) that can be found in our GitHub [Research](https://github.com/OALabs/research/tree/master/_notebooks) repository. Notes may contain errors, spelling mistakes, grammar mistakes, and incorrect code. Please keep in mind these are all rough drafts. Pull requests are welcome!
13 |
14 | # Notes
15 |
--------------------------------------------------------------------------------