HelpFIT
Go to navigation

Content Creation

The final form of the course page on https://courses.fit.cvut.cz/ is not created directly by the instructor, but is automatically generated by the Courses platform from the so-called source repository. The instructor usually finds this repository in the course group.

The process by which a course page is edited can be simplified into the following steps:

  1. The instructor creates and edits the content in the so-called source repository on GitLab.[1]
  2. After the changes are saved, Courses automatically generates the final form of the course page.[2]
  3. Once completed, the page is automatically published on https://courses.fit.cvut.cz/ in the specific course.
gen process cs
Figure 1. The process of editing a course on Courses. Simplified.

Source repository

You can find the repository from which the course page is generated as follows:

  1. Log in to the GitLab service.
  2. Go to the group of the specific course.[3]
  3. In the course group, go to the repository with the course pages.[4]
Caution:

You can edit this repository based on the assigned permissions.[5]

For an already existing course, content can be created in several ways:

  • Simple edits can be made directly in the web interface without the need for deeper knowledge or installation of any applications. See Web editor.
  • More complex edits (such as bulk changes) are recommended to be done locally using remote access and git. See Local edits.

Web editor

The GitLab interface is used for creating content in the web environment.

The process of publishing your changes starts automatically after a commit is made, see the last step of section Editing Files.

Local edits

For advanced work or bulk edits, it is recommended to make changes using the following procedure. This procedure also allows you to preview changes before publishing.

  1. Download Course Pages Generator.
  2. Download the source repository of the given course.[6]
  3. In the root directory of the downloaded repository, run the Course Pages Generator.
    1. One-time run course-pages public.
    2. Run with change monitoring course-pages --watch public (automatically generates a preview after each change).
  4. The final form (or its preview) can be found in the public folder of the downloaded repository, specifically in the index.html file.
    1. The file can be opened in any web browser; after each change, the page needs to be refreshed, for example by pressing Ctrl+R.
  5. Publish your changes by uploading the changes[7] to the course repository, using the following command sequence:
    1. git add .
    2. git commit -m "<Brief description of changes>"
    3. git push

Supported formats

One of the platform’s features is the ability to choose the format in which you create and edit course pages. Formats can be freely combined within a single course.[8][9]

The currently supported formats are:

Partially supported formats:

Previewing changes

When editing AsciiDoc and Markdown files on GitLab, you can preview an approximate final form in the Preview tab. However, this basic preview may not exactly match the final form that will be published on Courses. When using Web IDE, preview is not available.

Another way to preview changes before publishing is to generate the course page locally locally. Such a preview already reflects the final form that will be published on Courses.

There are also other ways to preview changes without having to download the repository. See Branches.

Branches

If you need to work on your course page continuously outside the main development branch, create a new branch first.[10] For more on creating branches, see Creating a Branch.

All changes made in a specific branch are published to the course page address with the suffix @<branch-name>.[11]

Example of branch usage

I need to work on preparations for the upcoming semester. For obvious reasons, I do not want to publish the changes immediately, but I do want to let my colleagues review and contribute to them.

For the MI-XYZ course, I create a branch named pripravy-na-B202, where I will store preparations for the upcoming semester. Colleagues can contribute to the branch freely. I can always find the current preview of changes at https://courses.fit.cvut.cz/MI-XYZ/@pripravy-na-B202

After creating a merge request, it is possible to discuss the individual changes with colleagues.

Once the merge request is accepted (a merge into the master branch has occurred), the changes in the target branch are automatically published.

The sidebar navigation displays all files located in the course website repository, regardless of their type.

If the file is of the supported format type, the navigation includes a link to the rendered HTML file. If the format is not supported, the navigation includes a download link. You can customize the navigation behavior in the settings—for example, hide specific files.

Item Names

The navigation attempts to display the most appropriate name. If the file has a title[12], it is used in the navigation; otherwise, the file name is displayed.

In the case of a directory, the generator attempts to find a file named index.*. If the index file has a title, it is used as the item name in the navigation.

The behavior of the navigation is demonstrated below. The file title-available.adoc has the title “File with a title” set inside it, and the file folder-with-index/index.adoc has the title “Folder with an index”.

navfolder cs
Figure 2. Example of navigation title behavior (directory structure on the left, resulting menu on the right).
  1. When creating content, it is recommended to follow the established conventions, see for example the conventions used on these pages. ↩
  2. This process may take several minutes. ↩
  3. The URL of the course group is usually in the form https://gitlab.fit.cvut.cz/BI-XYZ/ ↩
  4. The name of the course page repository usually begins with the course code. ↩
  5. If you do not have permission to edit the course page, contact the repository owner (usually the course guarantor). ↩
  6. You download (or clone) the source repository the same way you would clone any other repository. See Working with a Repository Locally. ↩
  7. We ask users not to perform git push with every small change unnecessarily, so as to save computational resources. ↩
  8. The generator automatically recognizes the file format by the file extension. ↩
  9. However, they cannot be combined within a single file. ↩
  10. The branch name can be chosen freely. ↩
  11. One special example of branch usage is semester branches – these branches are created automatically. ↩
  12. How to set a title is described for specific content types. For example, to set a title in AsciiDoc, see Metadata and attributes ↩