Formatting Tips#

Warning

This is all based on you having accepted the portfolio assignment on github and having a cloned copy of the template. If you are not enrolled or the initial assignment has not been issued, you can view the template on GitHub

Your portfolio is a jupyter book. This means a few things:

  • it uses myst markdown

  • it will run and compile Jupyter notebooks

This page will cover a few basic tips.

Managing Files and versions#

Important

This will be updated; new githut features change how it works

Organization#

The summary of for the part or whole submission, should match the skills to the chapters. Which prompt you’re addressing is not important, the prompts are a starting point not the end goal of your portfolio.

Data Files#

Also note that for your portfolio to build, you will have to:

  • include the data files in the repository and use a relative path OR

  • load via url

using a full local path(eg that starts with ///file:) will not work and will render your portfolio unreadable.

Structure of plain markdown#

Use a heading like this:

# Heading of page
## Heading 2
### Heading 3

in the file and it will appear in the sidebar.

You can also make text italic or bold with either *asterics* or __underscores__ with _one for italic_ or **two for bold** in either case

File Naming#

It is best practice to name files without spaces, underscores _ or hyphens - are both good. Each chapter or file should have a descriptive file name (with_no_spaces) and descriptive title for it.

Adding annotations with formatting or margin notes#

You can either install jupytext and convert locally or upload /push a notebook to your repository and let GitHub convert.
Then edit the .md file with a text editor of your choice. You can run by uploading if you don’t have jupytext installed, or locally if you have installed jupytext or jupyterbook.

In your .md file use backticks to mark special content blocks

```{note}
Here is a note!
```

```{warning}
Here is a warning!
```

```{tip}
Here is a tip!
```

```{margin}
Here is a margin note!
```

For a complete list of options, see the sphinx-book-theme documentation.

Configurations#

Things like the menus and links at the top are controlled as settings, in _config.yml. The following are some things that you might change in your configuration file.

Show errors and continue#

To show errors and continue running the rest, add the following to your configuration file:

# Execution settings
execute:
  allow_errors              : true

Using additional packages#

You’ll have to add any additional packages you use (beyond pandas and seaborn) to the requirements.txt file in your portfolio.