CSBlog v3

The csb blog

Build the blog

Prerequisites

• .NET 6.0 SDK

• Any conda distribution (e.g. anaconda or miniconda)

• dotnet tool restore to install the fornax tool that is used to build the website

• conda create --name csblog --file requirements.txt to set up the conda environment

develop locally in watch mode

• conda activate csblog (this has to be done once for each development session)
• go into the /src folder: cd src
• dotnet fornax watch to start the site generator in watch mode
• go to 127.0.0.1:8080 to see the blog

add content

posts are generated from the contents of folders in /src/posts.

To add a new post:

• add a folder with the name of your post to /src/posts

• create a post_config.md file. this file should only create metadata about your post, and must have this structure:

  ---
  title: <your post title>
  author: <your name>
  author_link: <a link>
  category: <post category>
  date: <YYYY-MM-DD>
  summary: <one-sentence summary of your post>
  preview_image: <images/your_image.png>
  ---
  

  • title is the title of your post
  • author is the author of the post (most likely your name)
  • author_link is a link that will be associated with your name. You can for example link your github or twitter account here
  • category is one of progress, studynote, advanced
  • date is the date of submission in ISO 8601
  • summary OPTIONAL. A one-sentence summary of your post. think about it as the hook for readers to click on it.
  • preview_image OPTIONAL. A link to an image that will be put on top of the post preview. Please use a small, 3 by 1 image for this.

• create a post.ipynb file that contains your blogpost. This notebook will be parsed and rendered to a html site. do not forget to save the notebook with cell output, as the notebook will not be executed on site generation.

post_config Dos and Don'ts

• Don't use unguarded : characters, as they are used to separate keys and values

  title: Yes: No <- nope
  

• Do guard sentences in " quotation marks. That way, you can even use : in your post titles and summaries

  title: "Yes: No" <- yes
  

post.ipynb Dos and Don'ts

• Do save notebook cell output. Notebooks are not run on site generation

• Don't put tables of content into your notebooks. TOC are generated on site generation for each post

• Don't use headers (any level of #) in markdown to emphasize text - it will be put into the table of contents and you might not want that if you only want to put emphasis. use ** for that.

Troubleshooting

PS C:\Repos\CSBiology\CSBlog> dotnet fornax watch
Couldn't find config.fsx
Generated site with errors. Waiting for changes...
[11:16:57] Watch mode started. Press any key to exit.
[11:16:57 INF] Smooth! Suave listener started in 21.195ms with binding 127.0.0.1:8080

You are probably not in the ./src folder.

.
.
.
starting jupyter --output-dir='C:\Users\<user>\AppData\Local\Temp\' nbconvert --to html C:\Repos\CSBiology\CSBlog\src\posts/implementation/consoleTools.ipynb
EX: An error occurred trying to start process 'jupyter' with working directory 'C:\Repos\CSBiology\CSBlog\src'. The system cannot find the file specified.
make sure to set up a conda distribution with nbconvert installed.
.
.
.

(and your page is rather empty)

You probably either have conda and/or nbconvert not installed
➡ install it

-or- you don't have it accessible via PATH
➡ add it to path -or-
➡ use Anaconda Prompt instead