Introduction

Introduction

Learn basic information about AMPER.

Why AMPER?

Because we really care about periodic variable stars. Seriously, if you are asking this question, you probably shouldn’t be here.

If you still have a lot of intriguing questions about AMPER, please reach Miloslav Zejda and Jan Janík. They will be more than happy to answer them all while offering you a nice cookie along with a cup of tea or coffee. Really, they don’t bite.

Updating this documentation

This documentation is a statically generated site. It is generated by HUGO framework along with Book theme. The generator converts a set of simple Markdown files into this fancy documentation site. All documentation source files are located at amper/docs directory.

Folder structure

Toplevel folders

Every HUGO site follows strict toplevel folder structure.

  • archetypes – This folder contains custom redefinitions of the theme archetypes. We are happy with the Book theme archetypes so far, thus we keep this empty folder just for reference. Do not forget to have the .gitkeep file in the folder since Git is not capable to handle empty directories.
  • contentMarkdown content of the documentation.
  • data – This folder contains any auxiliary data used by the template (TOML, YAML or JSON). See HUGO Tutorial for more information on this topic. So far we keep this folder empty. Do not forget to have the .gitkeep file in the folder since Git is not capable to handle empty directories.
  • layouts – This folder contains custom redefinitions of the theme layouts. We use it to inject AMPER shortcut icon (favicon.ico) into existing theme layout.
  • static – If you want to inject any static content, like an image or a file to download, you will need to upload it here.
  • themes – This folder contains a reference to the Book theme repository.
  • config.toml – Main configuration file defining generic site settings. The preferred format is TOML, although HUGO accepts YAML and JSON as well. The file extension should reflect the format.

In the vast majority of cases you can narrow your focus to content and static since those two are the only ones you will ever need to enter.

The content subfolder

The current content folder structure

  • about – Folder containing all sections of the About chapter.
  • features – Folder containing all section of the Features chapter.
    • how-to-do.md – Document containing Markdown for the How to do… feature.
    • _index.md – Document containing Markdown for the front page of the Features chapter. It actually contains the table of contents for the features.
  • menu – Folder containing menu definition.
    • index.md – Definition of the menu on the left.
  • about-amper.md – Document containing Markdown for About AMPER section.
  • registration.md – Document containing Markdown for Registration section.
  • terms-and-conditions.md – Document containing Markdown for Terms and Conditions section.
  • _index.md – The front page of the AMPER Documentation. In our case it is the front page of the Introduction* chapter)

Markdown header

Every single Markdown document needs to begin with a front matter similar to the following example:

---
title: Introduction
type: docs
---
  • title: Introduction – defines the string used as HTML title (the example above is the front matter for the Introduction page).
  • type: docs – This setting needs to be placed in every single document to enforce the correct content type, i.e., docs.

The Book theme can be used also for a site that combines documentation site with a blog platform. In that case we need to distinguish between docs and post content types. We do not want to use the blog feature of the Book theme, so we removed content/posts folder and we moved files from content/docs subfolder directly into the content folder. This non-standard structure prevents the Book theme from determining correct content type, thus it has to be set explicitly within the scope of front matter.

Inserting an image

The image needs to be saved into the amper/docs/static directory. Then you can use Markdown to insert the image.

![AMPER logo](amper-logo.png)

If you tend to a lot of images, you can place your images into a subfolder, e.g., amper/docs/static/images. Then you can reference them relatively to the amper/docs/static folder:

![AMPER logo](images/amper-logo.png)

AMPER logo

Hypertext references

The HUGO framework uses shortcode mechanism to deal with links and cross references. Unfortunately in the AMPER Documentation we use the following setting to open external links in new window or tab.

[blackfriday]
  plainIDAnchors = true
  hrefTargetBlank = true

Due to a bug in HUGO this setting prevent us from using cross reference mechanism in the menu. Instead we always need specify full path for internal links.

- [**Introduction**](/docs/)
  - [About AMPER](/docs/about-amper/)
  - [Registration](/docs/registration/)
  - [Terms and Conditions](/docs/terms-and-conditions)
- [**About**](/docs/about/)
  - [About AMPER](/docs/about/amper/)
  - [Credits](/docs/about/credits/)
  - [Facts](/docs/about/facts/)
  - [Versions](/docs/about/versions/)
- [**Features**](/docs/features/)
  - [How to do...](/docs/features/how-to-do/)

While this solution is clearly suboptimal, it is still bearable.

The easiest way how to insert a link in Markdown is to use an inline link.

Learn basic information about [AMPER](https://amper.physics.muni.cz).

More sofisticated approach is to use the reference links. The list of references should be placed at the end of the Markdown document.

Every [HUGO] site follows strict toplevel [folder structure].

[HUGO]: https://gohugo.io
[folder structure]: https://gohugo.io/themes/creating/#theme-folders

The reference string can differ from the link. It can be either a number or any unique string. The label is treated in case insensitive fashion.

Because we really care about [periodic][1] [variable stars][Variable star].

[1]: https://en.wikipedia.org/wiki/Periodic_function
[Variable star]: https://en.wikipedia.org/wiki/Variable_star