-
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:
+++
...
// Title in the larger font
heroTitle = "Hero Title"
// Brief text under the 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:
...
<!-- Section title -->
digitalThread_title = "Title"
<!-- text under the title -->
digitalThread_subtitle = "text here"
<!-- the image (just the image name and extension) -->
digitalThread_image = "example.png"
...
Here we have more parameters as there's now more content, it is as follow:
...
<!-- Section title -->
inspiredBy_title = "Title"
<!-- text under the title -->
inspiredBy_subtitle = "Text here"
...
Then we have the contents for each collumn:
<!-- Here the name before was chosen for the first column and after for the right column -->
<!-- Title at the top of this columns -->
inspiredBy_before_title = "Title"
<!-- Image name and extension -->
inspiredBy_before_image = "example.png"
<!-- The paragraph right under the image -->
inspiredBy_before_paragraph = "There were many..."
<!-- same can be said for the second columm -->
<!-- Title at the top of this columns -->
inspiredBy_after_title = "Title"
<!-- Image name and extension -->
inspiredBy_after_image = "example.png"
<!-- The paragraph right under the image -->
inspiredBy_after_paragraph = "There were many..."
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 -->
<!-- Left column -->
understand_documents_title = "Title"
<!-- Right column -->
understand_data_title = "Title"
<!-- 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!"
Content is at: /content/about/_index.md
The about page is currently separated in a few sections, we'll talk about each individually.
See bellow:
+++
<!-- Section Title -->
mission_title = "Our Mission"
<!-- Section subtitle -->
mission_subtitle = "What we are trying to achieve"
mission_content = [
<!-- Section content, each item in this list represents a paragraph -->
<!-- Separate the paragraphs with comma -->
"The community is striving to pull...",
]
+++
Here's where the Steering Committee members are listed(list currently taken from here). See bellow:
+++
<!-- Section Title -->
people_title = "Steering Committee"
<!-- Section Subtitle -->
people_subtitle = "The Steering Committee is responsible for all things OSLC"
members = [
<!-- List of member names (currently in alphabetical order) -->
"Member One",
"Member Two",
"Member Two"
]
company = [
<!-- List of member company they represent -->
<!-- As indicated in the content in this example, the indexes must match for each member -->
"Company of Member One",
"Company of Member Two",
"Company of Member Three"
]
+++
This list all the official OSLC supporters(List taken from here). See bellow:
+++
<!-- Section Title -->
supporters_title = "Supporters"
<!-- Section Subtitle -->
supporters_subtitle = "The many supporters of OSLC"
<!-- Supporters are separated by 3 types -->
<!-- Type 1 title -->
supporters_type_1_title = "Foundational Sponsor-level members"
<!-- Type 1 supporters list-->
supporters_type_1_list = [
<!-- Separated by comma -->
"supporter1",
]
<!-- Type 1 supporters url list -->
<!-- indexes must match -->
supporters_type_1_url_list = [
"http://www.supporter1.com",
]
<!-- Type 2 title -->
supporters_type_2_title = "Sponsor-level members"
<!-- Type 2 supporters list -->
supporters_type_2_list = [
"supporter2",
"supporter3",
"supporter4",
]
<!-- Type 2 supporters url list -->
<!-- indexes must match -->
supporters_type_2_url_list = [
"https://www.supporter2.com/",
"https://www.supporter3.com/",
"https://www.supporter4.com/",
]
<!-- Type 3 title -->
supporters_type_3_title = "Contributor-level members"
<!-- Type 3 supporters list -->
supporters_type_3_list = [
"supporter4",
"supporter5",
"supporter6",
]
<!-- Type 3 supporters url list -->
<!-- indexes must match -->
supporters_type_3_url_list = [
"https://www.supporter4.com/",
"https://www.supporter5.com/",
"https://www.supporter6.com/",
]
+++
See bellow:
+++
<!-- Section Title -->
faq_title = "Frequently Asked Questions"
<!-- Section Subtitle -->
faq_subtitle = "Your OSLC questions, answered. Select a question to reveal the answer"
<!-- List of Questions -->
faq_questions = [
"Question one",
"Question two",
"Question three",
]
<!-- List of Answers -->
<!-- indexes must match -->
faq_answers = [
"Answer one",
"Answer two",
"Answer three",
]
+++