|
|
@@ -1,26 +1,6 @@
|
|
|
# Website Content
|
|
|
-- [Content Updates](#content-updates)
|
|
|
- - [Small Updates](#small-updates)
|
|
|
- - [Major Updates](#major-updates)
|
|
|
-- [Creating New Post](#creating-new-post)
|
|
|
- - [Post Naming Convention](#post-naming-convention)
|
|
|
- - [Post Front Matter](#post-front-matter)
|
|
|
- - [Post Content](#post-content)
|
|
|
- - [Excerpt](#excerpt)
|
|
|
-- [Creating New Page](#creating-new-page)
|
|
|
- - [Page Front Matter](#page-front-matter)
|
|
|
-- [Shortcodes and Includes](#shortcodes-and-includes)
|
|
|
- - [Alert](#alert)
|
|
|
- - [Alert Banner](#alert-banner)
|
|
|
- - [Image](#image)
|
|
|
- - [Video](#video)
|
|
|
-- [Web Assets](#web-assets)
|
|
|
-- [Styling](#styling)
|
|
|
- - [Bootstrap Customization](#bootstrap-customization)
|
|
|
- - [CSS Guidelines](#css-guidelines)
|
|
|
-- [Submitting your Changes](#submitting-your-changes)
|
|
|
-
|
|
|
-# Content Updates
|
|
|
+
|
|
|
+## Content Updates
|
|
|
|
|
|
If you want to contribute and update the website, please follow the instructions below.
|
|
|
|
|
|
@@ -30,11 +10,11 @@ You can use any text editor to make changes. If you are using **Visual Studio**,
|
|
|
|
|
|
You are always welcome to create an issue to discuss your changes before you start working on them.
|
|
|
|
|
|
-## Small Updates
|
|
|
+### Small Updates
|
|
|
|
|
|
Creating an issue is not required for small updates, but it is recommended to let others know what you are working on. If you are not sure whether your update is small or not, please create an issue first.
|
|
|
|
|
|
-### What is a small update?
|
|
|
+#### What is a small update?
|
|
|
|
|
|
We can define small updates as changes to the content of the website:
|
|
|
|
|
|
@@ -45,9 +25,10 @@ We can define small updates as changes to the content of the website:
|
|
|
- Minor navigation or footer update
|
|
|
- This will update all pages containing the navigation or footer
|
|
|
|
|
|
-### Steps
|
|
|
+#### Steps
|
|
|
|
|
|
-**Note:** This guide assumes you are already familiar with updating files in GitHub.
|
|
|
+> [!NOTE]
|
|
|
+> This guide assumes you are already familiar with updating files in GitHub.
|
|
|
|
|
|
1. Go to the [Stride Website GitHub](https://github.com/stride3d/stride-website) repository
|
|
|
1. Locate the file you wish to edit
|
|
|
@@ -59,7 +40,7 @@ We can define small updates as changes to the content of the website:
|
|
|
1. Provide a title and description for your pull request, and click on `Create pull request` again
|
|
|
1. Wait for the review and merge
|
|
|
|
|
|
-## Major Updates
|
|
|
+### Major Updates
|
|
|
|
|
|
[Creating an issue](https://github.com/stride3d/stride-website/issues) is **required** for major updates, so that others can comment on your changes and provide feedback.
|
|
|
|
|
|
@@ -73,7 +54,7 @@ You would start with the local development environment, which is described in th
|
|
|
|
|
|
Then you would make your changes and test them locally. Once you are happy with the result, you can create a pull request to merge your changes into the `master` branch.
|
|
|
|
|
|
-# Creating New Post
|
|
|
+## Creating New Post
|
|
|
|
|
|
To create a new blog post, you can follow one of these methods:
|
|
|
|
|
|
@@ -82,7 +63,7 @@ To create a new blog post, you can follow one of these methods:
|
|
|
|
|
|
Either method will allow you to create a new blog post, so choose the one that best suits your needs.
|
|
|
|
|
|
-## Post Naming Convention
|
|
|
+### Post Naming Convention
|
|
|
|
|
|
`YYYY-MM-DD-post-title.md`
|
|
|
|
|
|
@@ -90,7 +71,7 @@ Replace `YYYY-MM-DD` with the date of the post and `post-title` with the title o
|
|
|
|
|
|
⚠️**Important SEO Note:** Ensure the file title includes essential keywords related to your post's content. This is crucial as the file title dictates the URL of the post, which plays a significant role in search engine optimization (SEO).
|
|
|
|
|
|
-## Post Front Matter
|
|
|
+### Post Front Matter
|
|
|
|
|
|
The file should start with the following front matter:
|
|
|
|
|
|
@@ -140,7 +121,7 @@ Default front matter, which is used for all posts, can be found in the `posts/po
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-### Image
|
|
|
+#### Image
|
|
|
|
|
|
The image specified in the front matter serves dual purposes: It appears in the blog listing at [Stride Blog](https://www.stride3d.net/blog/) and is used as the **og:image** meta tag for social sharing. Here are three ways to specify this image:
|
|
|
|
|
|
@@ -149,7 +130,7 @@ The image specified in the front matter serves dual purposes: It appears in the
|
|
|
- External image URL e.g. `image: https://i.imgur.com/7GVEiSR.jpg`
|
|
|
- If you are looking for Stride specific logo's or icons, have a look at the [Figma](figma.md) options.
|
|
|
|
|
|
-## Post Content
|
|
|
+### Post Content
|
|
|
|
|
|
Check the previous posts for an example of the post content. Ideally you should use the same format as the previous posts to preserve the consistency of the blog.
|
|
|
|
|
|
@@ -159,7 +140,7 @@ You can also use majority of the Bootstrap classes in your content if you combin
|
|
|
|
|
|
💡**Tip:** We have a folder called `_drafts` where you can store your drafts. These files are not published. Once you are ready to publish your post, you can move it to the `posts` folder.
|
|
|
|
|
|
-## Excerpt
|
|
|
+### Excerpt
|
|
|
|
|
|
The excerpt is the first paragraph of the post. Separated from the rest of the content by three dashes `---`. The excerpt is used in the blog post list, meta description and in the RSS feed.
|
|
|
|
|
|
@@ -180,11 +161,11 @@ Additional content goes here...
|
|
|
|
|
|
```
|
|
|
|
|
|
-# Creating New Page
|
|
|
+## Creating New Page
|
|
|
|
|
|
To create a new page, create a new file in the root folder or create a new folder and add an `index.md` file to it. You can use any templating language supported by Eleventy. We use Markup, html, nunjacks.
|
|
|
|
|
|
-## Page Front Matter
|
|
|
+### Page Front Matter
|
|
|
|
|
|
The page front matter works the same way as the post front matter. The only difference is that the `layout` property is required.
|
|
|
|
|
|
@@ -200,11 +181,11 @@ permalink: /my-features/ # otherwise it would be /features/
|
|
|
---
|
|
|
```
|
|
|
|
|
|
-# Shortcodes and Includes
|
|
|
+## Shortcodes and Includes
|
|
|
|
|
|
You can see examples here https://www.stride3d.net/blog/examples/.
|
|
|
|
|
|
-## Alert
|
|
|
+### Alert
|
|
|
|
|
|
To add an alert, use the following include, where:
|
|
|
|
|
|
@@ -223,7 +204,7 @@ To add an alert, use the following include, where:
|
|
|
{% include _alert.html type:'success' icon:'fa-face-smile' title:'No icon: Stride contributors are proud to announce a new release now running on .NET 6 supporting the latest C# 10.' %}
|
|
|
```
|
|
|
|
|
|
-## Alert Banner
|
|
|
+### Alert Banner
|
|
|
|
|
|
A global alert banner can be used for promotional purposes. The banner can be activated in `site.json`.
|
|
|
|
|
|
@@ -233,7 +214,7 @@ A global alert banner can be used for promotional purposes. The banner can be ac
|
|
|
|
|
|
The HTML can be updated in the `/_includes/alert-banner.html` file.
|
|
|
|
|
|
-## Image
|
|
|
+### Image
|
|
|
|
|
|
Add responsive images using shortcodes. Be sure to include a descriptive title, as it will improve your post's search engine visibility. Also, if possible, use the **webp** format for images, which can also be used for transparent images. This will improve the performance of your site.
|
|
|
|
|
|
@@ -267,7 +248,7 @@ Replace `title` with a descriptive title for the image, `url` with the image URL
|
|
|
<a href="destinationUrl" title="title" class="mb-2"><img alt="title" src="url" class="img-fluid" loading="lazy" data-src="url"></a>
|
|
|
```
|
|
|
|
|
|
-## Video
|
|
|
+### Video
|
|
|
|
|
|
We should consider hosting our videos on YouTube whenever possible.
|
|
|
|
|
|
@@ -293,7 +274,7 @@ Replace `id` with the YouTube playlist ID. This shortcode renders as:
|
|
|
|
|
|
To embed a video hosted elsewhere, use the following shortcode:
|
|
|
|
|
|
-### Hosting our own videos
|
|
|
+#### Hosting our own videos
|
|
|
|
|
|
`{% video 'url' %}`
|
|
|
|
|
|
@@ -304,7 +285,7 @@ Replace `url` with the video URL (e.g., .mp4 file). Make sure you have a matchin
|
|
|
<div class="ratio ratio-16x9 mb-2"><video autoplay loop class="responsive-video" poster="jpgUrl"><source src="url" type="video/mp4"></video></div>
|
|
|
```
|
|
|
|
|
|
-### How to encode videos
|
|
|
+#### How to encode videos
|
|
|
|
|
|
Videos can be generated by many software in various formats & size, so they might end up being incompatible with web browsers or mobile, or simply be way too large.
|
|
|
It is better to stick to a format with low requirements such as H264 baseline profile (works almost everywhere).
|
|
|
@@ -326,7 +307,7 @@ ffmpeg -i myvideo.mp4 -vframes 1 -f image2 -y myvideo.jpg
|
|
|
ToDo: Maybe we could provide a simple tool to do that without using command line.
|
|
|
|
|
|
|
|
|
-# Web Assets
|
|
|
+## Web Assets
|
|
|
|
|
|
Our main web assets are:
|
|
|
|
|
|
@@ -342,21 +323,21 @@ Our main web assets are:
|
|
|
- `search.liquid` - Renders as `search.json` contains search meta
|
|
|
|
|
|
|
|
|
-# Styling
|
|
|
+## Styling
|
|
|
|
|
|
-## Bootstrap Customization
|
|
|
+### Bootstrap Customization
|
|
|
|
|
|
Our website uses the [Bootstrap](https://getbootstrap.com/) framework, version **5.3**.
|
|
|
|
|
|
⚠️**Important:** Prioritize the use of Bootstrap's inherent styling before integrating any custom styles. You should be familiar with [Bootstrap Utilities](https://getbootstrap.com/docs/5.3/utilities/api/) which help you to achieve most of the styling requirements.
|
|
|
|
|
|
-## CSS Guidelines
|
|
|
+### CSS Guidelines
|
|
|
|
|
|
Our goal is to write as little CSS as possible to ensure the website remains lightweight. We maximize the utilization of the Bootstrap framework to achieve this.
|
|
|
|
|
|
Further, we are using also [FontAwesome](https://fontawesome.com/) free icons. The icons are loaded in the `src/_includes/css/main.css` file.
|
|
|
|
|
|
-# Submitting your Changes
|
|
|
+## Submitting your Changes
|
|
|
|
|
|
Assuming you have made all necessary changes and tested them on the development server, you can submit a pull request to the `master` branch. The pull request will be reviewed and merged by the website maintainers.
|
|
|
|
Vaclav Elias