How to create your own Course Site

Based on the fantastic Jupyter Book open source project Jupyter Book

This repository is a template for creating your own Course Site, which can be embedded into DTU Learn or other web services. In this way, the same content will be visible on both DTU Learn, and on the web. Everything is already set up, you alter or add content and see the changes applied on the website within a minute or two. If anything breaks, we can roll back to any previous version.

The point of PG Course Sites is to enable rapid and simple content creation, support content collaboration and sharing between PG courses and use tools which are Python relevant. All content can easily be migrate/converted to other services or solutions if needed. If we lack features, we can contribute to the underlying project and have it implemented.

To get started, it is useful to learn about the very few files and folders included in this repository. This is a demonstration project, so many of the files and folders are not needed and can be deleted or altered.

Files and folders

In your project, which you can find here DTU Compute Gitlab (Use the DTU Login tab or if from Compute, the DTU Compute tab), enter the project and click the pg_cs folder to see all the relevant files and folders. It should look something like this:

Lets edit a file

If you want to try to edit a file, try clicking the intro.md file and click Edit

(You may need to press Edit once more the first time).

This is a Markdown file, you can use standard Markdown syntax for content. If you press the Preview tab, you can see the expected output right away:

If you want to see what can be done with plain Markdown, see this cheatsheet: Cheatsheet

When you are done altering the file, scroll down and press Commit which will apply your changes and start updating the site:

Go to the frontpage of your website (if you altered the intro.md file, which is the frontpage) and you should see the alterations you made within a short while. You may need to refresh the page, before changes are seen. Your website address can be found in the description of the repository (above all the files in the project).

Structure

The structure is very simple. The only files needed to have the website running are the files outside the pg_cs folder (please do not touch) and these:

pg_cs/
├── _config.yml
├── _toc.yml
└── intro.md

Anything else can removed and are purely files and folders for demonstration purpose.

_config.yml

The config file is where you configure the project. You should not need to alter anything in this file but can do so, if you want to make changes.

_toc.yml (Table of Content)

This file is your table of content and will control which files are build, and how they all interconnect. You can alter this file and rearrange the site if you like, or include newly created files as well. Any file not listed in the toc, will currently not be build, but this can be changed in the configuration file if you wish.

For further explanation on the toc file: Toc file

intro

This is the frontpage of you website. You can alter this freely but not remove it.

File formats supported

This project supports several different file formats for content creation, these are the primary:

• Markdown files (*.md): Usually used to create text heavy, content pages. This project further supports the MyST Markdown language as well, which is not standard Markdown.

• ReStructuredText (*.rst): Used primarily within the Python community, basically does the same as Markdown, but may be better (or worse) for your use case.

• Jupyter Notebook (*.ipynb): Used if you want to show Notebook files on your website, they will be run during the website build process. ipynb files mainly makes sense to edit, if you do so in a Python Jupyter environment.

For all supported formats, please see the official documentation: File formats

You can use \(\rm\LaTeX\) directly on all pages LaTeX support

Upload or Create new files and folders

You can create/upload new files or folders by pressing the + sign:

This would also be the way to upload any images or pdf files you might want to include on the website.

Advanced use

For much faster workflow, you can git clone this repository to your laptop, and work with the files and folders directly. When done, you can git push the changes to lab.compute.dtu.dk and the site will build automatically (and store the latest changes).

Another route is to use the Web Editor in GitLab, which lets you alter multiple files simultaneously before committing:

Embedding into DTU Learn Course

Please read the DTU Learn support guide: Creating Custom links

When you create the Custom link, please set the option to Window mode so that the Learn menu stays in place in the top part of the browser.

If you embed the site into your Learn course, DTU students never have to leave Learn to see your content.

Inspiration

You can find multiple examples of content created in Jupyter Book right here: Examples

For Chemistry which might not feel at home initially, please have a look in this book, which also has interactive 3D models, and much more: Chem Example (You can turn and interact with the 3D models on the page) There are many options in general on how to utilize Python for teaching.

There are many more examples on the web which covers all/most fields.

Please proceed to dive into the full Jupyter Book documentation, for more advanced use cases: Jupyter Book Documentation

Credits

This project is created using the excellent open source Jupyter Book project in combination with several other open source projects.

Questions or comments, please contact mcla@dtu.dk