Skip to content

Report (Docsify-This)

Technical Specifications

  • The report must be a single web page containing one or more images (length constraints are specified elsewhere).
  • The web page must be published on the web with the Docsify⁠–⁠This service. This service takes as input the URL of a single Markdown file, possibly referencing the URLs of one or more images, and publishes that Markdown file as a web page (have a quick look at the Docsify⁠–⁠This now and then come back here; everything will be much clearer).
  • The Markdown page and images containing your report must be published on the web (for consumption by Docsify⁠–⁠This) as a Github public repository.

The entire process is very simple.

How to develop the required Markdown content

One of the many possible workflows is as follows:

  1. Create a Github account (if you do not have one already).
  2. Scroll down the Docsify⁠–⁠This page until you find the list of the available templates. These are public Github repositories that can be cloned and used as a starting point.
  3. Click on the "One Page template" and clone the Github repository, that will now become a public repository in your Github account.
  4. Start editing the home.md file. This file contains a concise yet very useful Markdown guide that will certainly suffice to your needs. I suggest you to throw away the portion that references an image hosted elsewhere and focus on how to reference images hosted on this repository (you will have to insert screenshots in your report).
  5. Copy the URL of the Github page that corresponds to that file, paste it in Docsify⁠–⁠This and see what happens.

Regarding step 4, keep in mind that you will have to edit home.md, this file will have to reference several screenshots and you will certainly need many iterations before obtaining the final result.

You may edit the content either directly on the Github web site, or on your PC with one of the many editors capable of rendering Markdown content. In the latter case you will have to upload your work to your Github repository, which can be done either "manually" or automatically by using Git, "the" professional tool for synchronizing local folders with a Github repository.

Local development with Git

Most software development tools provide integrated support for Git and I encourage you to use one of those tools (e.g., PyCharm, Visual Studio Code). You first have to install Git on your machine (independent of the development tool) and then use the development tool. They all follow the same pattern:

  1. Clone your existing repository based on its URL. You will be driven to the Github authentication page and you will have to authorize your tool to operate on that repository; then you will have to choose the local folder that will store the content of the repository.
  2. Work on your local files, previewing the result with your development tool.
  3. When you want to copy the intermediate result on Github, "stage" your local changes, "commit" them with an explanatory message and then "push" everything on Github. All these steps are driven by the development tool. Keep in mind that whenever you create a new file that you want to be part of the repository (e.g., a screenshot), you have to instruct Git that this file has to be "tracked". This detail is also driven by development tools.

An outline with the required steps with Visual Studio Code:

  1. Install the "GitHub Pull Requests and Issues" extension.
  2. From the "Source Control" view (look for it in the menus), clone your Github repository.
  3. Keep that view open while working (it will be on the left sidebar). You will see icons for staging, committing and syncing, as outlined above.

There are a lot of tutorials on how to use Git, but they might be not easy to follow for a beginner because Git is very general and thus quite complex. The "Introduction to GitHub in Visual Studio Code" in the Microsoft Learn web site is quite simple and well structured.