Skip to content
Docs
Code a website
Getting started

Getting started

To create a site with Osuny, the simplest solution is to generate it based on the admin, which uses the template. This template uses the osuny theme.

The admin template offers an up-to-date site configuration. It contains Hugo, the theme and scripts that facilitate updates. As the sites are generated with Hugo, the code must be installed locally.

This happens automatically when you create the site in the Osuny admin interface, you just need to clone the repository.

Before the AAA template, there was another template, called osuny-hugo-template, which used the theme osuny-hugo-theme. This template and theme are obsolete. It was subject to several redisigns, and itself succeeded the Jekyll theme, at the beginning of Osuny. The AAA reference refers to the article Qualité frontend : à la recherche du AAA, published on Lab noesya.

Install Hugo

⚠ The theme currently supports the 0.157.0 version of hugo. See modifier la version d’Hugo.io

On Mac, with Homebrew, use the command:

brew install hugo

This is the method we use in the noesya team. For other methods, the official installation documentation is available at gohugo.io.

Install Yarn

On Mac, with Homebrew, use the command:

brew install yarn

official installation documentation.

Clone the Git Repository

The Git repositories are created by Osuny, there is no longer a need to create them by hand. If you did need to do this by hand, you would start from the template page. Click on the “Use this template” button, then give a name and validate. In this tutorial we will use the name my-project.

Once the repository is created, it must be cloned locally. The theme is a git submodule. To clone with the theme, use the command:

git clone git@github.com:my-organisation/my-project.git --recurse-submodules

If you have forgotten --recurse-submodules at the time of the clone, you can add the theme afterward:

git clone git@github.com:osunyorg/theme.git --recurse-submodules
cd theme
yarn
hugo server

Run the server

The first time, we install dependencies:

cd my-project
yarn install

To run the server, we use the command:

yarn osuny dev

What now?

The general idea to develop your site based on Osuny is to proceed by following the following steps.

We don’t touch the theme osuny!

All modifications to create a site are made in the repo of the site, there is never a need to modify the theme itself (themes/osuny).

1. Hugo configuration

      • config.yaml

First, try to configure everything using the file /config/_default/config.yaml.

This allows you, for example, to define the position of the breadcrumb trail, the summary, the truncation length, or to choose between a list or grid layout for the news items. When something is not customizable in the config.yaml file, you proceed to step 2. The file is empty; you must find the variables in the documentation or in the theme itself and paste them into the file.

You can find available variables in: https://github.com/osunyorg/theme/blob/main/hugo.yaml

2. SASS configuration

      • _configuration.sass

https://github.com/osunyorg/theme/blob/main/assets/sass/_theme/_configuration.sass The file /assets/sass/_configuration.sass is used to define variables that will be used by the theme.

The available variables are listed here: https://github.com/osunyorg/theme/blob/main/assets/sass/_theme/_configuration.sass

3. SASS Style personalization

      • _style.sass

When a modification cannot be made using variables, you must write Sass code in the /assets/sass/_style.sass file.

To write CSS selectors, you can use the DOM or consult the theme files. Whenever possible, use the theme’s helpers and conventions (px2rem(20), @include media-breakpoint-up(desktop), etc.). This helps maintain consistency and avoid side effects, especially those related to responsive design.

4. HTML Overrides

    Finally, when styling alone isn’t enough, all the HTML markup can be modified by duplicating the theme files in the /layouts folder.

    Note that this should only be done as a last resort, because doing so will prevent you from receiving theme updates. When the theme evolves, you must update your own HTML files to maintain compatibility. Of course, your HTML modifications must take into account accessibility and clean design principles in the same way as the theme.