Skip to content

feat: build the Amplify previews with Astro #504

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jpoissonnet merged 2 commits into from
Sep 30, 2026
Merged

feat: build the Amplify previews with Astro #504

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4ebaaba
docs: explain how to contribute with Astro
jpoissonnet Sep 30, 2026
8ec1441
feat: build the Amplify previews with Astro
jpoissonnet Sep 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
245 changes: 176 additions & 69 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,122 +1,217 @@
# Contributing

## How to install the project?
The blog is built with [Astro](https://astro.build/). The Astro project lives in the `astro/` folder, while the content stays at the root of the repository:

### Using Visual Studio Code
- `_articles/`: the Articles, one Markdown file each.
- `_talks/`: the Talks (Last Friday Talks, meetups and conferences), one Markdown file each.
- `_data/authors.yml`: the Authors and Speakers.
- `_data/topics.yml`: the closed list of Topics.
- `images/` and `assets/`: static files, copied as is to the root of the site (`/images/...`, `/assets/...`).

1. Install Docker or Podman on your machine
2. Open the project in Visual Studio Code
3. Install the recommended [Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
4. When VS code prompts you, agree to "Reopen in Container"
5. The blog should be built, refreshed and opened in a preview tab automagically. ✨
- If not, you can run the "Jekyll Serve" VS Code task manually.
## How to run the blog locally?

### With Ruby and Gem
You need [Node.js](https://nodejs.org/) 22.12 or later (the CI and the previews use Node.js 26).

```shell
git clone https://github.com/BedrockStreaming/tech.bedrockstreaming.com.git
cd tech.bedrockstreaming.com
sudo gem install jekyll bundler
bundle install
npm --prefix astro ci
```

Then run this command to run a dev server locally.
Then run this command to start a dev server with live reload:

```shell
bundle exec jekyll serve
npm --prefix astro run dev
```

:warning: There are some issues to run this project on M1 archi for now.

### With docker
Open your browser on `http://localhost:4321` to see the blog.

You can use docker to run the tech blog locally.
:warning: The dev server does not serve `images/` and `assets/`: they are only copied when the site is built. To check your images, build the site and serve the result:

```shell
docker buildx build --platform linux/arm64 --load -t tech-blog .
docker run -it -v $(pwd):/var/content:ro -p 8080:8080 -p 35729:35729 tech-blog:latest
npm --prefix astro run build
npm --prefix astro run preview
```

Then open your browser on `http://localhost:8080` to see the blog.
The built site is written to `astro/dist`.

:warning: You may need to change the `docker buildx` command if you are not using an M1 Mac.
Entries dated in the future are hidden. To show them, as the pull request previews do, set `SITE_PREVIEW=true`:

```shell
SITE_PREVIEW=true npm --prefix astro run dev
```

## How to add an article to the blog?

All articles are listed in the `_articles` folder.
Each article is a Markdown file named like this `YYYY-MM-DD-article-slug.md` where date is the date of publication.
Set `date` and `permalink` in the front matter. A collection does not take the publication date from the filename.
:information: If you put a future date of publication, your article won't be visible until this date is passed.
Set `date` and `permalink` in the front matter: the publication date and the URL are not taken from the filename.

:information_source: If you put a future date of publication, your article won't be visible until this date is passed (and the site is rebuilt). It is visible in the pull request preview.

Make sure to complete the _frontmatter_ part of your Markdown file in order to define at least those attributes:
Complete the _front matter_ of your Markdown file with at least those attributes:

```markdown
---
layout: post
title: Title of your article
description: Description of your article visible in search page results
author: author_of_your_article
title: "Title of your article"
description: "Description of your article visible in search engine results"
author: [author_of_your_article]
language: en
date: 1970-01-01
permalink: /1970/01/01/article-slug.html
topics: [frontend]
---
```

We are using a community theme for Jekyll for this blog, you may find some useful examples here:
- [How to add Table of content for your blog post ?](https://sylhare.github.io/Type-on-Strap/2014/11/28/markdown-and-html.html)
- [How to use images in your post ?](https://sylhare.github.io/Type-on-Strap/2018/10/29/feature-images.html)
You can store your images in _images/post_ folder of this repository.
Don't forget to compress them for performances with tools like [TinyPNG](https://tinypng.com/)
- [How to add code examples ?](https://sylhare.github.io/Type-on-Strap/2014/08/08/Markup-Syntax-Highlighting.html)
- [How to add simple Diagrams with _Mermaids_?](https://sylhare.github.io/Type-on-Strap/2019/11/02/Tech-stuff-example.html#mermaid)
Mermaid is a really powerful tool to generate Diagram dynamically with some text.
Check [Mermaid documentation](https://mermaid-js.github.io/mermaid/#/).
- `layout` must be `post`.
- `language` is `fr` or `en`.
- `author` is an author ID from `_data/authors.yml`, or a list of IDs: `[first_author, second_author]`.
- `topics` is a list of keys of `_data/topics.yml`. It can be empty: `topics: []`.
- `permalink` is the URL of the article. By convention, use `/YYYY/MM/DD/article-slug.html`.

The front matter is checked when the site is built: a missing required attribute, an unknown attribute, a misspelled attribute or a Topic that is not in `_data/topics.yml` makes the build fail with an explicit error.

These optional attributes are also allowed:

```markdown
# Large image used when the article is shared on social networks
thumbnail: /images/posts/1970-01-01-article-slug/thumbnail.png
# Image displayed as the background of the article header
feature-img: /images/posts/1970-01-01-article-slug/header.jpg
# Old URLs that should redirect to this article
redirect_from:
- /an-old-url/
# URL of the original article, if it was first published elsewhere
canonical: https://example.com/original-article
# Text displayed on the homepage instead of the first paragraph
excerpt: "A short introduction to the article."
# Marker ending the excerpt, if it should be longer than the first paragraph
excerpt_separator: <!--more-->
```

### Excerpt

The homepage shows an excerpt of each article: the `excerpt` attribute if it is set, otherwise the first paragraph of the article.
To show more than the first paragraph, set `excerpt_separator: <!--more-->` and put `<!--more-->` where the excerpt should stop.

### Images

Store the images of your article in `images/posts/YYYY-MM-DD-article-slug/` and link them with an absolute URL:

```markdown
![Description of the image](/images/posts/1970-01-01-article-slug/diagram.png)
```

Don't forget to compress them for performances with tools like [TinyPNG](https://tinypng.com/).

### Code examples

Use fenced code blocks with the name of the language, they are highlighted when the site is built:

````markdown
```javascript
console.log('Hello Bedrock');
```
````

### Diagrams with Mermaid

[Mermaid](https://mermaid.js.org/) generates diagrams from text.
Write the diagram in a `<div class="mermaid">`, without any blank line inside the `div` (a blank line ends the HTML block and the rest is read as Markdown):

```html
<div class="mermaid">
flowchart LR
A[Source] --> B[Build] --> C[Site]
</div>
```

The Mermaid script is only loaded on pages that contain such a `div`.

### Table of contents

Put these lines where the table of contents should be displayed. It lists the headings of the article:

```markdown
* TOC
{:toc}
```

### Markdown syntax

Articles are written in [CommonMark](https://commonmark.org/help/) with the GitHub extensions (tables, strikethrough, task lists, autolinks). Some habits from other Markdown flavors don't work the same way:

- A line of raw HTML (such as `<br>`, `<hr>` or `</figure>`) starts an HTML block that runs until the next blank line: add a blank line after it before writing Markdown again.
- Put a single space after a list marker: `- item`, `1. item`.
- Tables need a header row, followed by the `| --- |` separator row.
- To open a link in a new tab, add `{:target="_blank"}` right after the link: `[Bedrock](https://www.bedrockstreaming.com/){:target="_blank"}`.
- `--` is rendered as an en dash (–) and `---` as an em dash (—).

### Publish your article

In order to add a new article, you should open a Pull Request on this repository.
A preview will automatically be deployed on AWS thanks to AWS Amplify service.
The CI builds the site, and a preview (including future-dated entries) is automatically deployed on AWS thanks to AWS Amplify service.

Don't hesitate to share your new post of **#proj-blog-tech-bedrock** slack room to ask for reviews from Bedrockers.
When you have 2 approves and no change requested, you can merge your Pull Request.
Once merged on `master`, the site is built and deployed to GitHub Pages automatically.

## Add an author

Edit `_data/authors.yml` to add an author (authors are sorted alphabetically).
Edit `_data/authors.yml` to add an author (authors are sorted alphabetically). The key is the author ID, usually the first letter of the first name and the last name:

```yaml
j_doe:
name: Jane Doe
avatar: /images/avatar/j_doe.jpg
url: https://www.linkedin.com/in/jane-doe/
```

`name` is required. `avatar` (a distant file or an image hosted in the `images/avatar` directory) and `url` are optional.

Authors could have a `name`, a `url` and an `avatar` (which could be a distant file or an image hosted in the `images/avatar` directory).
Then you will be able to use the author ID in the `author` key of the front matter of your articles and talks.

Then you will be able to use the author ID in the frontmatter post configuration key named `author`.
## Add a topic

Topics are a small, closed list: prefer an existing topic from `_data/topics.yml`.
If a new one is really needed, add it to `_data/topics.yml` as `key: Label`, then use the key in the `topics` of the front matter.

## Add a LFT replay

1. Create a file in the `_talks` folder name matching this format `YYYY-MM-DD-slug-of-your-article.md`
1. Create a file in the `_talks` folder named `YYYY-MM-DD-slug-of-your-talk.md`.
Use the date the talk was first given in public.
2. Add the configuration of metadata at the beginning of this file
> :warning: **To make your video appear on the Last Friday Talks page, set `eventName: Last Friday Talks`.**
> :warning: **To make your video appear on the Last Friday Talks page, set `eventName: Last Friday Talks` and a `youtubeId`.**
```markdown
---
layout: video
# Unique ID of the Youtube video clip
youtubeId: $$$$$$$
# Title of the article
title: Title of your article
youtubeId: $$$$$$$
# Title of the talk
title: "Title of your talk"
# Description (for SEO and context purpose)
description: Description of your article visible in search page results
# Authors of the article (can also be a list of authors such as: [first_author, second_author, third_author])
description: "Description of your talk visible in search engine results"
# Speakers of the talk (can also be a list: [first_speaker, second_speaker])
# The complete list of valid author IDs is in `_data/authors.yml`
author: author_of_your_article
author: speaker_of_your_talk
language: fr
eventName: Last Friday Talks
date: 1970-01-01
permalink: /1970/01/01/slug-of-your-talk.html
# Topics from _data/topics.yml
topics: [frontend]
---
```
3. Add content to the markdown file in order to add context to the video you are sharing.


## Add a conference

There are two ways to publish a conference where you were a speaker.
Please note that creating a post is more likely to help our external communication.
Please note that adding some content is more likely to help our external communication.

All talks whose `eventName` is not `Last Friday Talks` are displayed in the "Meetups & Conferences" page.
If there is a `youtubeId` key, the video is also added to the "Replay" section.

### Publish information about the conference

Expand All @@ -129,52 +224,64 @@ title: "Title of the conference"
date: 1970-01-01
author: conference_speaker
language: fr
eventName: ******
eventUrl: ******
youtubeId: ******
slideshareKey: ******
sponsored: true
hosted: true
eventName: "Name of the event"
eventUrl: https://example.com/event
permalink: /1970/01/01/title-of-the-conference.html
topics: []
---
```

That's all folks! Your conference will be displayed in "Meetups & Conferences" page.
If there is a `youtubeId` key, the video will also be added to the "Replay" section.

That's all folks! Your conference will be displayed in "Meetups & Conferences" page.

### Create a post to present the conference

1. Create a file in the `_talks` folder named `YYYY-MM-DD-slug-of-your-article.md`
1. Create a file in the `_talks` folder named `YYYY-MM-DD-slug-of-your-talk.md`.
Use the date the talk was first given in public.
2. Add the configuration of metadata at the beginning of this file:
```markdown
---
layout: conference

# Title of the conference
title: Title of your conference
title: "Title of your conference"
# Description of the page (for SEO and context purpose)
description: Description of your article visible in search page results
# from _data/authors.yaml
description: "Description of your talk visible in search engine results"
# from _data/authors.yml
author: conference_speaker
language: fr
# Public event name
eventName: ******
eventName: "Name of the event"
# Url to redirect to the event site (optional)
eventUrl: ******
eventUrl: https://example.com/event
# Youtube video id (optional)
youtubeId: ******
# Slideshare presentation key (from iframe integration) (optional)
slideshareKey: ******
# Link to the conference page (optional)
conferenceUrl: https://example.com/event/talk
# Bedrock sponsored the event? (default: false)
sponsored: true
# Bedrock hosted the event? (default: false)
hosted: true

# Topics from _data/topics.yml
topics: [backend]
permalink: /1970/01/01/slug-of-your-article.html
date: 1970-01-01
permalink: /1970/01/01/slug-of-your-talk.html
---
```
3. Add content to the markdown file in order to add context to the presentation you are sharing.

The Slides (`slideshareKey`) and the conference link (`conferenceUrl`) are only displayed with `layout: conference`.

## Redirect an old URL

To keep an old URL working after changing a `permalink`, list the old URLs in `redirect_from`, in the front matter of the article or talk:

```markdown
redirect_from:
- /an-old-url/
- /2019/01/01/an-older-url.html
```

Each old URL serves a small page that redirects to the new one.
19 changes: 19 additions & 0 deletions amplify.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
version: 1
frontend:
phases:
preBuild:
commands:
# Install Node with nvm when the build image does not provide it.
- if ! command -v node; then curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash; . "$HOME/.nvm/nvm.sh"; nvm install 26; fi
- node -v
- npm --prefix astro ci
build:
commands:
- SITE_PREVIEW=true npm --prefix astro run build
artifacts:
baseDirectory: astro/dist
files:
- '**/*'
cache:
paths:
- astro/node_modules/**/*
Loading