Ockam Website

This repository contains all of the content, code and build tools for Ockam.io.

Ockam website is built with a static site generator that is based on gatsby starter -> gatsby-gitbook-starter. Gatsby builds websites powered by the JAMStack, a modern architecture that uses JavaScript, APIs and Markdown without requiring the use of a database or server-side programming language.

Ockam.io utilizes GitHub actions, Azure Pipelines and runs on Azure CDN.

🚀 Quick start

Start developing.

Navigate into the site’s directory and start it up.

npm run start
Open the source code and start editing!

The site is now running at http://localhost:8000!

Note: You'll also see a second link: http://localhost:8000/___graphql. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the Gatsby tutorial.

Generating and managing MD files

Folder structure and urls

All files related to generating html from md files are stored under src/content folder.

However, the CI pipeline process mount under this directory, others repository defined in dependencies_repos.csv. So according to this file specification ( please check Depended repositories ) for entry like: https://github.com/masterborn;ockam-sample-documentation;4f3789304ad3a4421fc772cd59d95b71af98d4d9;/;documentation 'documentation' folder would be deployed under src/content/.

Folder structure reflects to generated url in project, so i.e:

src/content/documentation/general/index.md -> example.com/documentation/general
src/content/documentation/general/subpage.md -> example.com/documentation/general/subpage

Documentation pages order in sidebar menu

To order your documentation page in sidebar menu, just add order metadata field in metadata .md file. ie:

title: "Subpage 1"
metaTitle: "This is the title tag of this page"
metaDescription: "This is the meta description"
order: 2

Generals markdown managing approach

All assets should be stored inside under assets folder, ie. src/content/documentation/assets.

Using MDX

Thanks to MDX you can use any react component inside md files. Do do that you have to:

import component or data right after metadata

...
metaTitle: "This is the title tag of this page"
metaDescription: "This is the meta description"

---

import SampleComponent from '../sample/SampleComponent.js'
import json from '../sample/json.js'

Component path should be relative to current file.

Next, just use component like normal react element inside your md files:

...

### Some markdown header

<SampleComponent json={json} title="custom string" />

WARNING

There could be some issue while creating new/removing components/data which are imported to .md files. If in development mode throw some error just stop server, clean gatsby cache and run it again:

npm run clean
npm run start

Markdown files metadata fields

Below are listed described available metadata fields under a certain path of src/content folder:

blog

date Post date, used for sorting. Format: YYYY-MM-DD [REQUIRED]
title Title of post [REQUIRED]
description Description of post show in post list and homepage [REQUIRED]
author Author of post [REQUIRED]
authorAvatar Author avatar, relative path to md file
isHomepageFeatured Set true if should be visible in homepage shortcut blog section. Only 3 post will show there.
homepageFeaturedOrder Set post order ( from 1 to 3 )
metaTitle SEO meta title
metaDescription SEO meta description

all others

title Title string displayed on sidebar menu [REQUIRED]
order Integer value to ordering pages in sidebar menu three (In terms of particular branch only).
metaTitle SEO meta title
metaDescription SEO meta description
wideContent if set to true, makes content column in full width
redirect_from Redirects regarding to gatsby-redirect-plugin documentation

Sidebar menu items ordering

You can set order number to control sidebar item menu position. If there is no order metadata field, it would be ordered by slug(filename) by default

Depended repositories

All depended repositories are placed in in dependencies_repos.csv file. Each line represent one repository. One line include following parts:

ORGANIZATION;REPO_NAME;COMMIT;SRC_DIR;URL_PATH

Where

ORGANIZATION is github organization name
REPO_NAME is the repository name inside organization
COMMIT is specific commit id in repository
SRC_DIR is path in repository where MD files are stored. Use / to use root repository folder
URL_PATH is where you want to have final URL (/ is for front site; /example will end up with <website>/example)

Example repo definition:

masterborn;ockam-sample-documentation;4f3789304ad3a4421fc772cd59d95b71af98d4d9;/;documentation

Redirects

Redirecting markdown pages

To keep redirects in more readable and maintainable manner, please use redirect_from YAML frontmatter inside your md files, i.e:

title: Using Add-Ons
redirect_from:
 - /sample-redirect-address/
 - /another/old/url/

Above code will create redirects from this two URLs to URL of this md file.

For more details, please check plugin documentation

Redirect other pages

To redirect other url, please modify redirects.csv file, where first chunk is "from address" and second is to "to address", i.e:

/product/router;/product/hub

Entry above mean redirect /product/router to /product/hub Each line inside this file is new redirect entry

🧐 What's inside?

A quick look at the top-level files and directories you'll see in the project.

.
├── azure-pipelines.yml
├── cli/
├── config.js
├── dependencies_repos.csv
├── Dockerfile
├── gatsby-config.js
├── gatsby-node.js
├── package.json
├── package-lock.json
├── README.md
├── scripts/
├── src/
└── terraform/

azure-pipelines.yml: Definition of pipeline, used by Azure DevOps. Check 'depended repositories' for details.
cli/: Internall CLI, more information here.
dependencies_repos.csv: List of depended repositories, more can be read here.
Dockerfile: Docker for local development.
gatsby-config.js: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. (Check out the config docs for more detail).
gatsby-node.js: This file is where Gatsby expects to find any usage of the Gatsby Node APIs (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process.
package-lock.json (See package.json below, first). This is an automatically generated file based on the exact versions of your npm dependencies that were installed for your project. (You won’t change this file directly).
package.json: A manifest file for Node.js projects, which includes things like metadata (the project’s name, author, etc). This manifest is how npm knows which packages to install for your project.
README.md: A text file containing useful reference information about your project.
scripts/: All additional scripts used during build process.
src/: This directory will contain all of the code related to what you will see on the front-end of your site (what you see in the browser) such as your site header or a page template. src is a convention for “source code”.
terraform: Whole website infrastructure related stuff are served by Terraform.

💫 Deploy

Build the site for production.

Navigate into the site’s directory and run the build command.

npm run build
Serve the production build locally.

You can test the production build locally. Just run the following command to start a local HTML server.

npm run serve

franziskuskiefer / website