-
Notifications
You must be signed in to change notification settings - Fork 9
Content Structure (Edit Add content)
This is intended as a reference on how to add, remove or edit content from the website.
Table of Content
Header, Footer, Hero and Base Parameters
Before diving into specifics it will be helpful to have a short peak at how we're using Hugo to render the website's content.
In Hugo pages and their layout are defined using a folder structure. Inside the /content folder is where Hugo stores the content for each page. Inside that folder each sub-folder defines the website page hierarchy. For a page exists we need a markdown file. Those are used to store all the information in that page.
For the base pages representative of that hierarchy point Hugos identifies them by _index.md. this is mandatory as part of Hugo.
For instance, the contents of the homepage can be found at /content/_index.md which is what you see when you open "oslc.co". The same can be said for the About page content, which is found at /content/about/_index.md. The sub-folder about defines all pages inside oslc.co/about with the index file representing the base page for that folder.
However in some pages it makes sense to have sub-pages within that hierarchy. For example for News. /content/news/_index.md contains the information in oslc.co/news but every other markdown file in that folder represents a news post.. ie: /content/news/this-is-a-post.md would be found at oslc.co/news/this-is-a-post.
This should help you understand where to find the files you need for the content you wanna edit within Hugo.
In some scenarios is makes sense to put have all of a page content in a single "place". In a news post for instance there's no need to break down each paragraph of that article or news and have to call each of those individually in the markup, there's no need for it since the content expected is always the same and can be rendered within a single element of the markup. In Hugo this is how that's defined:
+++
//Everything within here need to be inside a parameters
+++
//everything else is considered "content"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent id lorem id dolor convallis aliquet. Fusce efficitur erat eget lorem varius, et imperdiet augue dictum.
In the markup all you'd need to grab all that content is:
<div class="some-content">
{{ .Content }}
</div>
Hugo then grabs the content of the page you're trying to load.
However within that same example it may be required for us to have certain information store separately so we can do something different with it. In the case of a news post we store the author's name and the date it was posted. Here's what that looks like:
+++
author = "Author Name"
date = "2018-01-23T10:00:00+02:00"
+++
Which we can reference as:
{{ .Params.author }}
or
{{ .Date.Format "Jan 2, 2006" }}
This allow more flexibility in how we structure the DOM and how to display certain information. Another practical example is when a page has sub-sections, each with differences either in content or layout, such as the about page for instance. Then the use of Parameters makes for a lot more flexibility to the markup and the layout which wouldn't be possible otherwise, unless the content was in the markup, which is not desirable.
I hope this makes it a bit clearer moving forward as to the structure that can be expected in the markdown files.
The header links are defined in /config.toml. There you'll find a section with the following:
# Main Menu
[[menu.main]]
name = "Why?"
indentifier = "why"
url = "/why"
weight = 1
That's how a link is defined, in the header markup we iterate through item in menu.main to populate the header. So it's important to have the information be properly setup or it may not reference it in the right way. In this case:
name = The text you can see in the link (in the example "Why?"
indentifier = not as important as we're not currently doing any filtering or anything special with a specific item
url = The link url to that page
weight = The order in which it will appear with 1 being the first index
So if we want to add a link named Library, listed as the last link and that point to a page with a image library for instance we would have something like:
...
[[menu.main]]
name = "Library"
indentifier = "library"
url = "/library"
weight = 9
As of right now we advise caution when adding links, as there's limited space of how many links can exist before filling the entire header and causing headaches. 8 links seems to be the sweat-spot that will fit a decent amount of links even in the smaller desktop screens out there.
As of the writing of this document there aren't any links or much content in the footer aside from OSLC's social media links. I'll update the document when this changes.
The title and sub-title of each page is defined in the Parameters of that page. For the title heroTitle and heroSubtitle for the subtitle:
+++
...
heroTitle = "Hero Title"
heroSubtitle = "Here you can give a brief description of what lies ahead!"
+++
There are a few base parameters that are quite important:
- title = this content goes to the markup title which can be seen in the browser tab
- date = published or document date
Note: For now we don't use any other base parameters, will update it in case that changes
Content is at: /Content/_index.md
The home page is currently separated in a few sections, we'll talk about each individually.
This section is composed of 3 parameters:
...
digitalThread_title = "Title" //Section title
digitalThread_subtitle = "text here" //text under the title
digitalThread_title = "example.png" //the image (just the image name and extension)
...
Here we have more parameters as there's now more content, it is as follow:
...
inspiredBy_title = "Title" //Section title
inspiredBy_subtitle = "Text here" //text under the title
...
Then we have the contents for each collumn
//Here the name before was chosen for the first column and after for the right column
inspiredBy_before_title = "Title" //Title at the top of this columns
inspiredBy_before_image = "example.png" //Image name and extension
inspiredBy_before_paragraph = "There were many..." //The paragraph right under the image
//same can be said for the second columm
inspiredBy_after_title = "Title" //Title at the top of this columns
inspiredBy_after_image = "example.png" //Image name and extension
inspiredBy_after_paragraph = "There were many..." //The paragraph right under the image
This section had to be broken down a bit more since we now have more rows. And since they are not the same in term of content using something like a list wasn't possible here. See bellow:
//Base section parameters
understand_title = "Title"
understand_subtitle = "Subtitle"
//Column titles
understand_documents_title = "Title" //Left column
understand_data_title = "Title" //Right column
//Row info
//Every row has at least a image and a paragraph
//In the parameter name you can tell which column it belongs to
//The _n_ is replaced by the row number in the file
understand_documents_n_image = "example.svg"
understand_documents_n_paragraph = "Paragraph under the image"
understand_data_n_image = "example.svg"
understand_data_n_paragraph = "Paragraph under the image"
//For the first row there are two parameters used for the note under the paragraph
//(only one the column documents is shown but there are the same values for .._data_.. as well)
understand_documents_1_note = "URL represented by" //Text
understand_documents_1_icon = "fa-link" //fontawesome icon (see reference bellow)
//And the last row have a list of examples of mashup applications
//separated by comma
understand_documents_4_mashup = [
"Google Search",
"Mozilla Firefox",
"Google Analytics"
]
//For the _data_ column there is a second list because we add links to the original resource
understand_data_4_mashup = [
"IBM RCLM",
"IBM RELM",
"Memtor Graphics Context",
"Koneksys KLD"
]
//On the second list keeping the indexes matched is vital.
//Otherwise the link will go to the wrong item in the list
understand_data_4_mashup_urls = [
"https://www.ibm.com/us-en/marketplace/application-lifecycle-management",
"https://www.ibm.com/us-en/marketplace/engineering-analytics",
"https://www.mentor.com/products/sm/context-sdm/",
"https://github.com/koneksys/KLD"
]
For fontawesome class names see fontawesome.io/icons/ There click on the desired icon to see the class that references that icon (only put in the class of the icon, the other classes are already added in the markup.. ie: fa-check, fa-list)
Benefits the base section content such as the title and subtitle but all else is held in three lists. See bellow:
...
//Base content
benefits_title = "Title"
benefits_subtitle = "Subtitle"
//Title of each benefit
benefits = [
"Benefit 1",
"Benefit 2",
"Benefit 3",
...
]
//Description of each benefit
benefits_description = [
"Lorem ipsum...",
"Lorem ipsum...",
"Lorem ipsum...",
...
]
//icon of each benefit (from font awesome)
benefits = [
"fa-unlock",
"fa-refresh",
"fa-puzzle-piece",
...
]
//Once again, matching the indexes is necessary
...
Much simpler section, see bellow:
// Section title
specifications_title = "Specifications"
// Section paragraphs (It was made this way in case more paragraphs need to be added)
specifications_paragraphs = [
"paragraph 1",
"paragraph 2"
]
This section contains a list of images and has some differences over the others. See bellow:
// Section title
supporters_title = "Supported By"
// This is the text after the logos
supporters_outro = "And many more!"
// Now here there are two lists, the first simple and for the images
supporters = [
"logo.png",
"logo.png",
"logo.png",
...
]
// This list adds a class to the image, controlling it's maximum size
supporters_size = [
"full",
"eighty",
"fifty-five",
...
]
Classes are supported in steps of five from "full" to "fifty" and control the width of the element. This was necessary given the standardized aspect ratio of the images, and since the images expand to width squared logos can look much larger than narrow rectangular ones. So this provides some control in how they look without having to change the markup or the stylesheets.
See bellow:
// Section title
news_title = "Latest News"
// Section subtitle
news_subtitle = "Annoucements, Articles, Updates, and many more!"