Style Guide
Selcukes welcomes your contributions to our documentation! This document describes the options available for creating content for the site, along with some guidelines and conventions.
Markdown
This site uses Docusaurus version 2 Beta. Docusaurus uses the remarkable Markdown processor to convert GitHub Flavored Markdown into HTML. Docusaurus Markdown supports Basic Markdown Syntax and most Extended Syntax. You can see which features are supported here.
Frontmatter
At the top of each docs page, you need to include these things:
| Variable | Description |
|---|---|
id | A brief string that uniquely identifies the page within its parent folder. The id and the name of the file should be the same. |
title | The main title of the page. This value will automatically be rendered using the H1 style at the top of the page. |
sidebar_label | This is what will appear in the left hand navigation tree for the page. |
description (optional) | This is what appears when the page is referenced in a Google search result. |
keywords (optional) | A list of terms that help categorize the page for SEO purposes. |
It looks like this in the document:
---
id: style-guide
title: Style Guide Introduction
sidebar_label: Style Guide
description: The Selcukes Documentation Style Guide
keywords:
- contributing
- style
- markdown
---
Introduction
The first paragraph of the documentation should set the user's expectations for what they will find on the page. Describe the key benefits to the user, but do not include links.
Headers
For accessibility and SEO reasons, never have an H4 header that isn't under an H3 header, or an H3 header that isn't under an H2 header.
- H1 headers should never be used in a document since the title is automatically generated as an H1.
- H2 headers are used for SEO, so make sure they succinctly represent what a user will find on the page in that section.
- H3 headers are included in the page's table of contents on the right, so make sure the title describes something a user might want to directly navigate to.
- H4 headers are to emphasize things within a subsection of the page; these can be longer than the other headers if needed because they aren't included in the Table of Contents.
Markdown Code:
## H2 Header
### H3 Header
#### H4 Header
Content
All words are rendered in the same paragraph even with line breaks, so long as there isn't an empty line. As such, it is good practice for each line to be less than 120 characters long for readability, when possible.
Markdown | |
Display | This will all be on one line. The empty line above creates a new paragraph. This forces a soft return |
Images
All image files should be included in the rameshbabuprudhvi.github.io/static/img directory, in a sub-directory that
corresponds to the referencing directory. (e.g., images for a document in the rameshbabuprudhvi.github.io/docs/contributing directory
would be located in the rameshbabuprudhvi.github.io/static/img/contributing directory.
To add an image from that directory, you need to import a special method by placing this line below the Frontmatter, but above the Introduction
import useBaseUrl from '@docusaurus/useBaseUrl';
and then reference the image as follows:
<img src={useBaseUrl('img/contributing/my-image.png')} alt="All images should have alt text" width="250"/>
Videos
Any referenced videos need to be from a Selcukes YouTube account. The suggested iframe code structure is as follows:
<iframe width="560" height="315" src="https://www.youtube.com/embed/-RDh1ukLN8w" frameborder="0" allow="accelerometer;
autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
Tabs
Tabs are a great option when an example is different in different contexts. The primary usage of tabs on this site is to illustrate the same example in multiple languages. Ideally, these examples will exist in Java, Node.js, Python, Ruby, and C#, and the tabs should be placed in that order.
When a page includes multiple sets of tabs, use a groupId so when the user selects a particular tab,
all tabs with that ID will switch to the selected tab.
To use tabs, you need to import two special methods by placing these lines below the Frontmatter, but above the Introduction:
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
and then use the tabs as follows:
Markdown | |
Display |
This would include information or examples for Java This would include information or examples for JavaScript |
Inline Code
To refer to a single class or method name within a sentence, place single backticks around the name.
Markdown | |
Display | This comment refers to the |
Code Blocks
The best way to display code is with code blocks. Markdown will highlight each language differently, so it is helpful to specify which language you are using, and it's a good idea to include a title with the code block as well.
Markdown | Custom Title |
Display | Custom Title |
Code References
The Selcukes Open Source Team created a plugin for use with Docusaurus to allow us to reference code on GitHub
rather than duplicating code in this repo. Ideally all code displayed in the Selcukes documentation points to code in
one of the demo-<language> repos on
Selcukes Training GitHub Org.
When referencing code, include the language, "reference" and a title indicating what the sample shows.
The URL for the link can be for the entire file, or include specific line numbers at the end.
To ensure that code examples do not go stale and can be easily updated,
all code references should reference a tag instead of
a branch name or a commit hash. For our demo-<language> repos, we are doing semantic versioning with docs-<version>.
So, we will create and use docs-1.0 or docs-1.1, etc., as needed.
To create a new tag in one of the Selcukes owned repos:
git tag -a -m 'reference for Selcukes documentation' docs-<version>
git push origin --tags
Markdown | Example Test |
Display | Example Test |
Expanding Code Blocks
If you have an especially large code block that you'd like to reference on the page, but do not want
it to take up too much space on the page by default, we encourage the use of details elements.
HTML | |
Display |
|
Admonitions
There are four types of Docusaurus admonitions:
- Note - Relevant information.
- Tip - A user should do this.
- Caution - A user should pay attention to this.
- Warning - A user might do something dangerous!
Markdown | |
Display | note Relevant information for you. tip You should do this. caution You should probably pay attention to this. warning You are about to do something dangerous! |
Context Limited
There are two ways to provide context for users for when special conditions or limitations apply to designated information.
Badges
Badges are color-coded images that apply to entire pages or large sections of documentation:
Blue badges are used for everything except for deprecated information, which is indicated with a Gold badge.
HTML | |
Display | Beta Enterprise Only iOS Only Live Testing Only Early Access Deprecated |
Highlighted Text
For information in a subsection or in a table that needs additional context, use a span element with
one of the highlight classes. These can also be used to indicate that the content only applies to specific versions of a
technology.
HTML | |
Display | selcukes Cloud only Docker only Cypress Playwright version >= 1.12 Testcafe Puppeteer only |
Cards
For overview pages that have four categories, we often use these Boxes. Note that you can't use Markdown inside this HTML.
HTML | |
Display |