Staging your content
We don't have a good staging system right now. We'll be able to show you your work before it goes live, but if you want to see how things will render while you're working on them, the only option is to download the main repo and run a local Jekyll server.
To use the Jekyll setup, you'll need a Ruby setup with bundler
installed. gem install bundler
should do the trick.
- Clone this repo
- Add your content repo as a submodule in the
/collections
directory - Run
bundle install
in the root of the repo - Run
bundle exec jekyll serve -l
- Open a web browser to
http://localhost:4000
The -l
flag turns on LiveReload and incremental builds, so as you edit your content the web browser should automatically refresh when you save the document. Only pages being modified are rendered again, so if you change a title and it doesn't show up properly on an index page, you need to touch
the index page to regenerate it. Or kill the server and run jekyll build
to force the entire site to render.
Where your content will exist on the web
Once it's edited and merged, your content will be available at https://cool.devo.build/collections/...
. The ...
will be the directory path from the parent repo you contributed to. If you're creating in the Tutorials repo and your markdown file is called my-cool-tutorial.md
in the root of that repository, the url would be https://cool.devo.build/collections/tutorials/my-cool-tutorial
.
The front matter included in your content will determine where else on the site your content is surfaced. It will be available under its parent collection and in the content listing the Collections page, under tag pages for the tags you specified, and under the Use Case category you specified.
Content comes from repositories
The root devo.build site is fairly spartan. Most content in it is provided by external GitHub repositories that are added as submodules and imported when rendering the site.
A content repository is a repository containing nothing but Markdown and image assets. It contains an index.md
, Markdown pages for each piece of content (optionally sorted into subdirectories), and an assets
folder which contains any media assets used in the pages (images, PDFs, videos, audio). Each of these types has a few specific requirements that need to be adhered to.
/collections/REPO_SUBMODULE/
index.md (see below)
Markdown.md (see below)
assets/*
(Note that we're using the word "collections" to represent like groups of content, more akin to "series" than what "collections" means to Jekyll.)
Collection index.md
Each collection repository must contain an index.md
file in its root. This file serves as the project overview. In addition to the required front matter, any content in this page will be displayed above a listing of the pages that comprise it. Only the front matter is required.
A submodule repository can have more than one collection. The index.md
file is what will be served if the url path to the parent directory is called, but additional .md
files with the same front matter keys can also exist and will be displayed as additional collections. Each piece of content can only belong to one collection, though.
Project front matter
The index.md file (and all collection indexes) should have the following front matter. Uppercase values must be customized, lowercase values must not be modified.
---
layout: collection
title: PROJECT_TITLE
series: SERIES-SLUG
description: ONE_LINE_SUMMARY
thumbnail: RELATIVE_PATH_TO_THUMBNAIL_IMAGE
---
The thumbnail should be a minimum of 250x150px. It will be resized and cropped (if needed to fit the aspect ratio) when displayed. At this time we're requesting that all collections and all submitted content have at least one image, even if it's simply a screenshot of a tutorial in action. These thumbnails are used to offer better visual navigation and help prevent a "wall of text."
The series
key defines the slug you'll use to assign content to the collection, so it must be unique. We may eventually run into issues with name clashes, but we'll manually curate until we have a better solution.
Multiple collections per repo
If you wanted to break a repository up into multiple collections, you would simply add a new index file with a different name.
For example, if the directory is "/collections/tutorials", the index.md
file in that directory would be for "Tutorials." But if you wanted a "Getting Started" collection as well, you would create getting-started.md
and add the appropriate front matter. As long as it has the series
key, it will be viewed as a collection.
The URL for the Getting Started collection would be "https://.../collections/tutorials/getting-started" but it would appear at the same level as all other collections in navigation.
Pages
Each project repo (and the root repo) can contain as many pages written in Markdown as you like. The only technical requirement for a page is that it contain the appropriate front matter. There are stylistic guidelines that will be enforced in the content, but any text file with the .md
extension and the requisite front matter will render as part of the site.
Within a project repo, directories become parts of the url (permalink) for the page. Submodule repos are added within the /collections
directory, and the base URL for any collection is devo.build/collections/PROJECT-SLUG
. The slug will be assigned by the maintainers when the submodule is added.
(The collections
directory is purely for organization. It's entirely possible to create other parent directories. As long as they contain the right formatting, there can be as many as needed. Room for future expansion, as needed.)
Required front matter
---
title: PAGE TITLE
parent: series-slug
tags: [TAGS]
thumbnail: RELATIVE_PATH_TO_THUMBNAIL_IMAGE
date: YYYY-MM-DD HH:MM
description: ONE_LINE_SUMMARY
---
The date should be the date you plan to publish. If there's any delay in publishing, we'll update the date for you.
The thumbnail can be any image from your content that can represent it, no resizing necessary. If you want to generate a custom thumbnail, just make an image at least 800px x 800px and include it in the assets folder. Thumbnails are displayed cropped, and cropped differently in different views, so your image shouldn't try to convey vital information.
See Tagging Pages
Optional front matter
-
modified
: If you update a post with new content (or corrections), you can add amodified
key with a new date. Don't change the publish date, though. The modified key will be enough to let us surface updated content without disrupting the (mostly) chronological publishing system. (hint: there's a script in the cool.devo.build repo that can use to update the modified key for all changed markdown files prior to doing a commit.) -
categories:
is an array containing one or more category tags. See Tagging Pages for a list of available categories. -
author:
can be a block of YAML data, or if the author has been permanently added to the site by the maintainers, a slug will be provided for the author to use.To specify author data in the front matter, use a block like this. Other than "name," all fields are optional; fill out what's appropriate and leave out what's not:
author: name: Brett Terpstra bio: Oracle DevRel Writer, developer, blogger, podcaster home: https://brettterpstra.com twitter: ttscoff github: ttscoff gitlab: ttscoff bitbucket: ttscoff stackoverflow: ttscoff codepen: ttscoff youtube: BrettTerpstra facebook: ttscoff linkedin: brettterpstra instagram: ttscoff avatar: https://cdn3.brettterpstra.com/images/bt-mark.png location: Minnesota links: - label: Random Link url: https://example.com/one/ - label: Second Link url: https://example.com/two/ email: brett@example.com
If you fill all this out once and there's a good chance you'll write again in the future, we'll pull all of this info into the authors data file and assign you a slug. Once you have a slug, you're author section just looks like:
author: brett-terpstra
Of course, once that happens you'll have to make pull requests to update your bio, but that should be manageable.
-
toc: true
will enable a sidebar table of contents, automatically generated from headers in the page -
You can manually add links to the left sidebar, below any author bio, using:
sidebar: - links: - url: https://developer.oracle.com/proximasafe-intro/ title: Proxima Safe Part 1 - url: https://developer.oracle.com/proximasafe-part-2/ title: Proxima Safe Part 2 - url: https://developer.oracle.com/proximasafe-part-3/ title: Proxima Safe Part 3
-
To disable either or both sidebars and make content wider:
toc: false author_profile: false
Tagging Pages
Tags and categories should be chosen from available options. If you need a tag or category that does not exist yet, add it to your post but specify in the pull request (or open an Issue) that you'd like the new tag added to the site.
Categories
The categories key is an array, surrounded by square brackets, with multiple values separated by a comma:
categories: [cloudapps]
# or with multiple categories...
categories: [clouddev, java, games]
Available Categories, use all that apply. Only include the short version (slug):
-
Build and Run Cloud Native Apps
slug:
cloudapps
-
Cloud-Native Software Development on OCI
slug:
clouddev
-
Build, Move, and Modernize Applications
slug:
modernize
-
Java, GraalVM, and Helidon
slug:
java
-
Enterprise Cloud Native Development
slug:
enterprise
-
Personal Cloud Services
slug:
personal
-
Video Games, Servers, and Development
slug:
games
-
Top Frameworks for Top Languages
slug:
frameworks
These categories are based on the content goals for the DevRel program. New categories can be suggested as needed, but if you can fit your content into one of these, well, that's just excellent. Hats off to you.
Tags
Available Tags are listed here, try to use at least one of each type. If no appropriate tag exists in a section, you can add a new tag to your post. In the pull request, please specify the new tag and to which type it belongs.
I'm including the list --- as it exists at the time of this writing --- for reference, but it will definitely be changing faster than I'll remember to update, so please check the link above for the current list.
topics:
- hardware
- oci
- pytorch
- iot
- streaming
- serverless
- rpi
- apex
- alwaysfree
- jupyter
personas:
- fullstack
- frontend
- devops
- backend
- architect
- robotics
- arvr
- datascience
- gamedev
- dbre
- community
languages:
- python
- javascript
- typescript
- go
- ruby
- terraform
frameworks:
- tensorflow
- micronaut
- nodejs
- spark
- flask
Assets
Assets are stored in an assets
directory in each repository. All links to these assets should be relative to the location of the linking page. If your page is at /collections/tutorials/page-1.md
and your assets folder is at /collections/tutorials/assets/
, then your link to an image from page-1.md
would look like assets/my_image.jpg
.
Please name assets with a prefix based on the page they're being used in. This is to avoid name clashes with other content. If you're writing a tutorial called "Node on OCI," any asset used should be named with the prefix node-on-oci-*
.
Images
Insert images using the Liquid tag:
{% img [classes] assets/image.jpg [WIDTH HEIGHT] "CAPTION" "ALT TEXT" %}
This tag allows us to convert the asset to a proper <picture>
tag with a srcset
. Use only the base image and size in the tag. If a matching @2x version is present in the same folder as the image, the generated tag will make it available to hi-res displays.
Classes are optional but can be used to align an image left, right, or center:
alignleft
: floats image left, text flows aroundalignright
: floats image right, text flows aroundaligncenter
: container becomes full width, image centered, text breaks above and below
WIDTH and HEIGHT are also optional but are encouraged. These should be numbers only, no px
or other specifier. These should be the width and height of the 1x image, e.g. the size it will display on the page.
The last two strings are also optional but encouraged. If only one string is given, it's used as alt text. Alt text tells screen readers and content scrapers what the image is, and is important for accessibility. Please always include at least one quoted string in the tag.
If two quoted strings are provided, the first one becomes both an image caption, visible on the page. The second string is the alt tag.
Example:
{% img alignright assets/my-tutorial-circuit.jpg 500 300 "Circuit diagram" %}
Image Sizes
Images can not be displayed at a width greater than 1200px. Your base image size should never be wider than 1200. Please size your images appropriately and optimize them for web.
If possible, please provide two images for every asset, one at the size you want it displayed, and one at exactly twice the pixel dimensions, named with @2x (image.jpg and image@2x.jpg). An 800x500px image.jpg would have a 1600x1000px image@2x.jpg counterpart.
To insert a YouTube video as a responsive embed, simply use:
{% youtube VIDEOID %}
Callouts
Use block quotes to create callouts, with Kramdown IAL syntax to add formatting. There are two types available, notice and alert. The formatting works like:
> This is my note.
> It can have a couple of lines
{:.notice}
> This is an alert. It gets colored in yellow.
{:.alert}
Snippets
Fragments will be made available soon.
When linking the Oracle Always-Free Tier signup, please use this in place of the link: {{ site.urls.always_free }}
. This will insert a tracking link for you.
Oracle Cloud Infrastructure Free Tier account. [Start for Free]({{ site.urls.always_free }}).
Style
These are very random notes I've collected while editing some of the initial copy, mostly syntax-related. They are not organized, and are definitely a bit rambly. I'm sure I'll have a bunch more in short order... I'll update with a cleaned up, official "style guide" soon. But please do give them a quick read and avoid some pitfalls we'll have to ask you to fix.
Headers
- The title front matter will be used as an h1 at the top of the page, don't repeat it in the content
- Divide long pieces up with headers, starting with level two (
##
), and increasing for sub-sections in sequence, e.g. don't jump from a level two to a level four - Title case lede headlines (the
title
key), but simply capitalize subheaders within the content - Include an empty after headlines
Code samples
- Use fenced code blocks for multi-line code, or commands that wrap to multiple lines (allows better formatting and syntax highlighting)
- Start a code block with triple backticks (
```
) - include language specifier when possible, e.g.
```ruby
. You can useconsole
for terminal instructions
- Start a code block with triple backticks (
- When showing shell commands in fenced code, use a single
$
at the beginning of the line to represent the prompt - File names, paths, and commands in paragraphs should be surrounded in backticks to mark them as
code spans
Lists
- Use 4 spaces to indent lists. You can get away with 1 tab instead, but please do not indent lists with two spaces, it leads to trouble if we ever change the rendering engine we use. Four spaces will work everywhere
- Use numbered lists when it represents a sequence
- As long as the first item in the list starts with "1.", it doesn't matter what numbers follow. Every line can be "1." or they can be out of order, they'll be automatically straightened out when it renders. Don't waste a lot of time tweaking the numbering if your list gets out of order
- First letter of list items should be capitalized unless the list items each finish a sentence preceding the list
- One-sentence list items should not end in a period. If a list item contains multiple sentences, periods are optional. If you use a period on one, though, use a period on every item in that list
- Don't, in general, use a list for a single item. If you're breaking up a long list by putting headers between groupings, a single-item list is fine
- To include paragraphs in a list item, add a blank line before the paragraph and indent it four spaces (or one tab) beyond the indent of the parent list item
- You can do the same with fenced code blocks, starting the fence four spaces/one tab from the parent list item's indent level
Emphasis
- Use italics for emphasis in prose copy (
I *emphasized* this
). Either asterisks (*) or underscores (_) are fine - Use bold for things like
- emphasizing a key word
- product names
- menu/button titles
Quotes
- Use block quotes for quotes, starting each line with
> TEXT
- Quote styling will be handled automatically, so don't add emphasis (italics/bold) to entire lines
- Force line breaks by including a double space at the end of the line (or
<br>
, see General style/formatting) - Attribution (source) should start with
---
(em dash), and be linked if appropriate
Links
- When linking text, make the content of the link actually describe where the link will go
- Bad: Click here for more details
- Good: Check out our tips page for more details on Markdown formatting
- When showing an entire URL in the copy (as opposed to hyperlinked text), it should either be self-linked with angle brackets (e.g.
<https://example.com>
) or marked as a code span with single backticks - Whenever representing a dummy URL in examples, use
https://example.com
.example.com
is a ICANN protected url for this purpose and it avoids myriad potential security issues with using hijackable domains
General style/formatting
- Avoid using "smart quotes" (curly quotes). Use straight single and double quotes
- If you're referring to a tool or product that is only ever lowercase, you don't have to capitalize it at the beginning of a sentence
- No one will yell at you if you include
<br>
tags to force line breaks. Different Markdown syntaxes allow for different formatting, but the standard is two spaces the end of a line. However, some text editors trim whitespace on every save and it's easy for them to disappear. A<br>
will stick around. They'll be there for you. We won't begrudge you that