GitHub - llvm/www-template (original) (raw)

www-template

This is a Hugo theme for the LLVM Compiler Infrastructure project. It provides a clean and modern design for the LLVM website.

Table of contents

• Features
• Installation
• Configuration
• Creating new website
• Creating new pages
• Using YAML data files
• Creating new shortcodes

Features

• Clean and modern design
• Responsive layout
• Easy configuration via hugo.toml or config.toml

Installation

1. Clone the repository into your Hugo site's themes directory:
   git clone https://github.com/llvm/www-template themes/www-template
2. Update your site's hugo.toml or config.toml file to use the theme:
3. Install Post CSS CLI
4. Run your site locally with the theme:

Configuration

hugo.toml

The hugo.toml file contains various configuration options for the theme. Below is an excerpt with explanations for each option:

baseURL = 'https://example.org/' languageCode = 'en-us' title = 'The LLVM Compiler Infrastructure'

[markup.goldmark.renderer] unsafe= true

Navigation Bar Menu

[[menus.main]] name = 'Getting Started' pageRef = '/' weight = 10

[[menus.main]] name = 'Docs' pageRef = '/docs' weight = 20

[[menus.main]] name = 'Blogs' pageRef = '/blogs' weight = 30

[[menus.main]] name = 'Resources' pageRef = '/resources' weight = 40

[[menus.main]] name = 'Doxygen ' pageRef = '/' weight = 1 parent = 'Resources'

[[menus.main]] name = 'GitHub' pageRef = '/' weight = 2 parent = 'Resources'

[[menus.main]] name = 'Code Review' pageRef = '/' weight = 3 parent = 'Resources'

[[menus.main]] name = 'Downloads' pageRef = '/downloads' weight = 50

[module] [module.hugoVersion] extended = false min = "0.116.0"

Hero section links

[params] logo = "images/logo.png" navbar_logo = "images/logo.png" subtitle = 'The LLVM Project is a collection of modular and reusable compiler and toolchain technologies. Despite its name, LLVM has little to do with traditional virtual machines. The name "LLVM" itself is not an acronym; it is the full name of the project. ' no_robots = true

[params.banner] visible = false description = "Feedback for this website" [[params.banner.buttons]] text = "Feedback Form" url = "https://docs.google.com/forms/d/1irmZ1vSHtYUqTFQIUqBxl2rjbW4mpaRdzrpBxsqxrsE/" [[params.banner.buttons]] text = "Old Website" url = "https://llvm.org"

[[params.hero_section_buttons]] title = "Get Started" url = "/get-started" type = "primary" [[params.hero_section_buttons]] title = "Releases" url = "https://releases.llvm.org" type = "secondary"

only first 4 links will be displayed

[[params.hero_section_links]] title = "Latest Release" icon = "ri-hashtag" url = "/" [[params.hero_section_links]] title = "Upcoming Events" icon = "ri-play-large-line" url = "#upcoming_events" [[params.hero_section_links]] title = "Read the Docs" icon = "ri-book-open-line" url = "/" [[params.hero_section_links]] title = "Explore subprojects" icon = "ri-projector-line" url = "/"

Table of contents config

[markup] [markup.tableOfContents] startLevel = 2 endLevel = 4

Footer config

[params.footer] title = "The LLVM Compiler Infrastructure"

[[params.footer.columns]] title = "LLVM" links = [ { text = "Features", url = "#" }, { text = "Documentation", url = "#" }, { text = "Blog", url = "#" }, { text = "FAQ", url = "#" }, { text = "Resources", url = "#" }, { text = "Download", url = "#" } ]

[[params.footer.columns]] title = "Dev. Resources" links = [ { text = "Doxygen", url = "#" }, { text = "Sources (GitHub)", url = "#" }, { text = "Code Review", url = "#" }, { text = "Bug Tracker", url = "#" }, { text = "Green Dragon", url = "#" }, { text = "LNT", url = "#" }, { text = "Scan Build", url = "#" }, { text = "llvm-cov", url = "#" }, { text = "Compile-time tracker", url = "#" } ]

[[params.footer.columns]] title = "About LLVM" links = [ { text = "Mission", url = "#" }, { text = "Community", url = "#" }, { text = "Events", url = "#" }, { text = "Sponsors", url = "#" }, { text = "Contact", url = "#" } ]

Configuration Options

• baseURL: The base URL for the site.
• languageCode: The language code for the site.
• title: The title of the site.
• markup.goldmark.renderer.unsafe: Enable unsafe HTML in markdown.
• menus.main: The main menu items for the site.
• params.logo: The logo for the site.
• params.navbar_logo: The logo for the navbar.
• params.subtitle: The subtitle for the site.
• params.banner: The banner configuration.
  • visible: true or false, whether the banner is visible.
  • description: The description for the banner.
  • parqams.banner.buttons:
    * text: The text for the button in the banner.
    * url: The URL for the button in the banner.
• params.hero_section_buttons: The buttons displayed in the hero section.
  • title: The title of the button.
  • url: The URL for the button.
  • type: The type of the button (primary or secondary).
• params.hero_section_links: The links displayed in the hero section.
  • title: The title of the link.
  • icon: The icon for the link.
  • url: The URL for the link.
• markup.tableOfContents: The table of contents configuration.
  • startLevel: The starting level for the table of contents.
  • endLevel: The ending level for the table of contents.
• params.footer: The footer configuration.
  • title: The title of the footer.
  • columns: The columns in the footer.
    * title: The title of the column.
    * links: The links in the column.
    * text: The text of the link.
    * url: The URL of the link.

Creating New Website

To create a new website using the theme, follow these steps:

1. Create a new Hugo site:
2. Change into the new site directory:
3. Clone the theme into the themes directory:
4. Install Post CSS CLI
5. Update the config.toml file to use the theme:
6. Run the site locally:
7. Open the site in your browser:
8. Customize the site by updating the configuration options in the config.toml file.

Creating New Pages

To create new pages, use the following command:

hugo new /_index.md

For example, to create a new page named about, run the following command:

Front matter for the new page will be created automatically. Update the front matter with the desired content e.g.:

title: Sample Page description: Markdown tutorial and syntax examples for common elements. date: 2023-01-15T09:00:00-07:00 draft: false tags: ["markdown"] toc: true

You can find and example page in the content/sample-page/_index.md file.

Using YAML Data Files

The theme supports YAML data files for defining content. To use YAML data files, create a new file in the data directory, refer to the other data files for the structure.

Then use the datamap.html shortcode.

Usage of datamap.html Shortcode

{{< datamap "data_file_name" "data_array" "title" "description" "expected_result"

}}

• data_file_name: The name of the data file.
• data_array: The name of the array in the data file.
• title: The title of the data item.
• other fields: The fields of the data item.

Creating New Shortcodes (using YAML Data Files)

Create a new shortcode (e.g. new_short_code.html) in the layouts/shortcodes directory. In the shortcode file, use the datamap.html shortcode to display the data.

It is a HTML file, so you can use HTML tags to style the data.

More on shortcodes can be found in the HUGO docs here.