Landing pages
We create landing pages in several locations. The most obvious one is docs.superoffice.com
. The contents and layout of this page are set in our build templates in a private repository. If you have suggestions or want to request changes main page, you can create a site feedback issue.
Level 2: category pages
A category page is a landing page for a specific area, for example, SuperOffice APIs or onsite installation, to simplify navigation to the various topics within that area. The contents and layout of these pages are configured in files named index.yml and adhere to a custom schema. Unlike the main page, these YAML files are located in the corresponding folders in the content repositories and can thus be forked and edited.
The first line says ### YamlMime:Category
, followed by title, summary, and metadata.
Then you'll find various blocks of links:
- highlightedContent - holds several simple cards, each card points to a single piece of content.
- productDirectory (optional) - can have a section title and summary, it contains several cards, each one points to a product page.
- conceptualContent - can have a section title and section summary as well as several cards. The cards must have a title and contain at least one link.
- tools (optional) - may have a section title and a section summary, the section must consist of several cards. Each card is meant to point to a Language, Framework, CLI, Tool, or Extension.
- additionalContent - is the most flexible section. It allows for a section title, section summary, several cards, and a footer section
The URLs are relative to the YAML file and can be either external, point to a Markdown file of a specific page, or to another index.yml.
Examples
highlightedContent:
items:
# Card
- title: "System requirements"
itemType: reference
url: requirements/index.md
# Card
- title: "Customer Service"
itemType: overview
url: ../service/index.yml
# Card
- title: "Installation guide (Web)"
itemType: overview
url: install/index.yml
# Card
- title: "Release notes"
itemType: whats-new
url: ../../release-notes/index.md
conceptualContent:
title: "Get SuperOffice up and running"
summary: "Regardless of whether this is your first installation or an upgrade, security is essential."
items:
# Card
- title: Migrate to CRM online
summary: Take SuperOffice to the cloud
links:
- url: ../online/migrate/index.md
itemType: how-to-guide
text: "Migration guide"
- url: ../email/service/migrate.md
itemType: concept
text: "Migrating Service mailboxes"
- url: ../online/system-requirements.md
itemType: reference
text: System requirements for SuperOffice CRM Online
Note
Yaml is very picky when it comes to whitespace and indentation.
Level 3: sub-category pages
A sub-category page is similar to a category page but its focus is narrower. For example, while the SuperOffice API landing page is a category, authentication is a sub-category.
The first line will say ### YamlMime:SubCategory
, followed by title, summary, and metadata.
There's just one block: landingContent.
Examples
title: CRM Onsite
summary: Welcome to the area where you can find relevant links to all things related to installation, upgrade, and migration.
metadata:
title: Set up SuperOffice successfully
description: SuperOffice Onsite installation, upgrade, and migration.
so.product: onsite
so.topic: hub-page
# ...
landingContent:
# Card
- title: Onsite authentication
linkLists:
- linkListType: learn
links:
- text: Overview
url: overview.md
- linkListType: get-started
links:
- text: NetServer Core
url: onsite/sosession/index.md
- text: NetServer Custom Proxies
url: onsite/custom-proxies/index.md
- text: REST WebApi
url: onsite/webapi/index.md
- text: COM API
url: onsite/com/index.md
# Card
- title: Feedback
linkLists:
- linkListType: how-to-guide
links:
- text: Create an issue
url: https://github.com/SuperOfficeDocs/superoffice-docs/issues
# Card
- title: Editing and authoring
linkLists:
- linkListType: how-to-guide
links:
- text: How to edit an article in browser
url: how-to-edit-an-article-in-browser.md
- text: How to edit an article locally
url: how-to-edit-an-article.md
- linkListType: reference
links:
- text: Style guide
url: style-guide/index.md
- text: Guidelines for formatting
url: style-guide/formatting.md
- text: Our branch strategy
url: branch-strategy.md
- text: Git cheat-sheet
url: git-cheat-sheet.md
Common tasks
Tip
You may click on the Edit button when viewing the page to suggest an improvement on the existing article content.
Fix typo or change title, description, or link text
- Locate the correct index.yml.
- Edit the value of the
title
,summary
, ortext
field.
Fix broken link
- Locate the correct index.yml.
- Edit the url.
Tip
To test that the path and file name are correct, Ctrl-click the link in VS Code. If the target file opens, you're good to go.
Add a link to an existing card
Locate the correct index.yml.
Decide which entry you'll add it after.
Add a text-url pair at the appropriate level. You'll need minimum 2 lines:
- text: REST WebApi url: onsite/webapi/index.md
Some blocks require you to specify
itemType
, otherslinkListType
. Follow the established pattern.
Add a new card to the landing page
Locate the correct index.yml.
Decide which block you want to add it to, and where in the sequence.
Copy an existing card in that block and modify it. The simplest card is in the highlighted content:
- title: "System requirements" itemType: reference url: requirements/index.md
Delete card or link
Deleting a card or a link is trivial. However, the schema specify a minimum and maximum number of items and you have to make sure you don't exceed those limits.
You'll find some of the important validation rules as comments in the index.yml files. For example:
# highlightedContent section (optional)
# Maximum of 8 items
highlightedContent:
# Card with summary style
additionalContent:
# Supports up to 3 sections
sections:
- title: Resources # < 60 chars (optional)
summary: "System requirements, compatibility, config, and debug" # < 160 chars (optional)