From 6f539fa2527cf469c91517baac4777f69c00ac9f Mon Sep 17 00:00:00 2001 From: Thib Date: Wed, 31 Jan 2024 11:16:11 +0100 Subject: [PATCH 01/16] Explain how to publish to the blog --- CONTENT.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 CONTENT.md diff --git a/CONTENT.md b/CONTENT.md new file mode 100644 index 000000000..acaca92f2 --- /dev/null +++ b/CONTENT.md @@ -0,0 +1,55 @@ +The matrix.org website is powered by [Zola](https://www.getzola.org/), a [static site generator](https://en.wikipedia.org/wiki/Static_site_generator). It ingests content in rather human-friendly formats, and turns it into the beautiful matrix.org website we all love. The format you need to use depends on the type of content you want to add. + +This documentation is about helping you create new content that the static site generator will accept. To get your content actually deploy on matrix.org, you need to be familiar with git, GitHub and Pull Requests. If that's not the case, we suggest either finding someone who is and can help, or dropping us a line in the [Matrix.org Website chat room](https://matrix.to/#/#matrix.org-website:matrix.org). + +## Publishing to the blog + +Articles on the blog are written in the markdown format. Markdown should generally be the same everywhere, but there are small variations around what you can or can't do with it. Zola supports the [CommonMark variant](https://commonmark.org/help/) of Markdown. + +All the blog posts are sorted in directories. They live in `/content/blog/YEAR/MONTH/`, with `YEAR` and `MONTH` being the year and month in digit format, e.g. [`/content/blog/2024/01/`](https://github.com/matrix-org/matrix.org/tree/main/content/blog/2024/01). + +One surprising bit about Zola is that both the `YEAR` (e.g. `2024`) and `MONTH` (e.g. `01`) need to have a `_index.md` with the following content to be rendered by the generator: + +``` ++++ +transparent = true +render = false ++++ + +``` + +Once this structure is in place, you need to write the actual blog post. It is a single text file ending with the `.md` extension. There are two sections in the file: a _frontmatter_ containing all the metadata (e.g. title of the post, date of publication, author, section), and the content itself. + +In the frontmatter, make sure to format the date as `year-month-day` (e.g. `2024-01-22`) then append `T` to specify the time as `hour:minute:seconds` (e.g. `12:30:00`) and add a final `Z` to specify that the time is on the UTC time zone. We use UTC to make it easier for humans to figure out which blog post is going to be published first if two blog posts are issued on the same day. + +You can use the following template to create a new blog post: + +``` ++++ +date = "2024-01-22T12:30:00Z" +title = "Exciting news from the Foundation!" + +[taxonomies] +author = ["Jane Smith", "John Doe"] +category = ["Foundation"] ++++ + +## Matrix is taking over the world + +We're excited to announce that our plan to conquer the world worked. We are everywhere, and people seem to be happy about it! + +## Our positive impact + +We are privacy-centric and don't want to track people individually, but we want to make sure we still have a positive impact. In our apps, we allow people to express their frustration whenever something doesn't work. +``` + +### Adding a picture for the socials + +You know the cool previews that are generated on socials (Mastodon, LinkedIn, and others) when you paste a link? Matrix.org supports them! By default if you don't specify any, it is going to use [this placeholder](https://github.com/matrix-org/matrix.org/blob/main/static/blog/img/matrix-logo.png) image. + +If you want to add your own, drop it in the PNG format in [`/static/blog/img`](https://github.com/matrix-org/matrix.org/tree/main/static/blog/img), and add the following lines to your frontmatter (between the two rows of `+++`): + +``` +[extra] +image = "https://matrix.org/blog/img/YOUR-IMAGE.png" +``` From e90852cd524a7eabf66a0e5bff3affeadd299d6d Mon Sep 17 00:00:00 2001 From: Thib Date: Wed, 31 Jan 2024 12:23:28 +0100 Subject: [PATCH 02/16] Add instructions on how to add clients --- CONTENT.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/CONTENT.md b/CONTENT.md index acaca92f2..f07f79952 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -53,3 +53,73 @@ If you want to add your own, drop it in the PNG format in [`/static/blog/img`](h [extra] image = "https://matrix.org/blog/img/YOUR-IMAGE.png" ``` + +## Adding new projects to the ecosystem + +All of the ecosystem projects information are in subdirectories of [`/content/ecosystem`](https://github.com/matrix-org/matrix.org/tree/main/content/ecosystem/). + +### Clients + +Matrix clients are listed in [`/content/ecosystem/clients`](https://github.com/matrix-org/matrix.org/tree/main/content/ecosystem/clients). Every client has its individual page, so every client is represented by a markdown file. Most of the information is living in the _frontmatter_, between the two `+++` rows in a `.md` file. + +To add a client, add your client's logo (ideally in SVG format) as `your-client-name.svg` and a markdown file as `your-client-name.md` file (no space allowed in the file name) under [`/content/ecosystem/clients`](https://github.com/matrix-org/matrix.org/tree/main/content/ecosystem/clients) and fill it with the following template: + +``` ++++ +title = "My client name" +template = "ecosystem/client.html" +[extra] +thumbnail = "your-client-name.svg" +maintainer = "Your name or organisation" +maturity = "PICK ONE" Stable OR Beta OR Alpha OR Obsolete" +repo = "https://github.com/example-org/example-repo" +matrix_room = "#your-matrix-room:example.com" +licence = "PICK ONE" +latest_release = "2022-11-02" +featured = false + +[extra.features] +e2ee = false +spaces = false +voip_1to1 = false +voip_jitsi = false +threads = false +sso = false +multi_account = false +multi_language = false + +[extra.packages] +windows_installer = "https://example.com/download" +macos_installer = "https://example.com/download" +google_play_store.app_id = "com.example.app" +f_droid.app_id = "com.example.app" +apple_app_store = { app_id = "id1234567890", org = "example" } +flathub.app_id = "com.example.app" +webapp = "https://chat.example.com" ++++ + +Supercharge your communications with Example Client. +``` + +- For the `maturity`, please pick one of + - `Stable` if your software has been running in production for a little while and if you are confident in the sustainability of the project + - `Beta` if there are rough edges but people won't lose any data + - `Alpha` if your software is still experimental + - `Obsolete` if your software is no longer maintaines +- `featured` should be left to false. We are working on [processes to formalise which project should be featured or not](https://github.com/matrix-org/matrix.org/issues/1584). +- For the `licence`, please use [one of the identifiers listed by the SPDX](https://spdx.org/licenses/) +- All of the properties under `extra.packages` are optional: only add the installation methods your project supports! +### Bridges + +### Servers + +### Integrations + +### SDKs + +### Hosting providers + +## Adding documentation + +## Adding sponsors + From 03d19ecaef46e2069242b700e0615d100a5c22a2 Mon Sep 17 00:00:00 2001 From: Thib Date: Wed, 31 Jan 2024 12:42:35 +0100 Subject: [PATCH 03/16] Add instructions for images and YT player in blog posts --- CONTENT.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/CONTENT.md b/CONTENT.md index f07f79952..5e19f84c7 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -43,6 +43,27 @@ We're excited to announce that our plan to conquer the world worked. We are ever We are privacy-centric and don't want to track people individually, but we want to make sure we still have a positive impact. In our apps, we allow people to express their frustration whenever something doesn't work. ``` +### Adding pictures in your post + +It is possible to add pictures to your posts in markdown. First you need to drop the pictures in [`/static/blog/img`](https://github.com/matrix-org/matrix.org/tree/main/static/blog/img). Then, in the markdown file itself add the following line + +``` +![A description of the picture](/blog/img/your-picture-name.png) +``` + +### Embedding a YouTube player + +Embedding the YouTube Player loads cookies from youtube.com. This is fairly invasive in terms of privacy, and breaches the GDPR since we don't have a cookie banner to get visitor's consent to do so. + +Whenever you want to add a YouTube video to a blog post, go to YouTube to view the video. The URL should look like `https://www.youtube.com/watch?v=S1nBXjWWHoU` at the minimum, and can look a bit more complex like `https://www.youtube.com/watch?v=S1nBXjWWHoU&list=PLl5dnxRMP1hWycy97GpncT3G3KaFn1MI6&index=2`. + +Copy the series of characters after the `v=` and before the first `&` that you meet in the URL. In our example, that is `S1nBXjWWHoU`. This is the id of the video on YouTube. + +In your markdown file, add this line to embed the YouTube player in a way that respects the user consent. + +``` +{{ youtube_player(video_id="S1nBXjWWHoU") }} +``` ### Adding a picture for the socials You know the cool previews that are generated on socials (Mastodon, LinkedIn, and others) when you paste a link? Matrix.org supports them! By default if you don't specify any, it is going to use [this placeholder](https://github.com/matrix-org/matrix.org/blob/main/static/blog/img/matrix-logo.png) image. From 6c91a450a626d10e7b71ac4bdb87ea1bc88a083e Mon Sep 17 00:00:00 2001 From: Thib Date: Wed, 31 Jan 2024 15:32:31 +0100 Subject: [PATCH 04/16] Typo --- CONTENT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTENT.md b/CONTENT.md index 5e19f84c7..ae9cbc2de 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -126,7 +126,7 @@ Supercharge your communications with Example Client. - `Stable` if your software has been running in production for a little while and if you are confident in the sustainability of the project - `Beta` if there are rough edges but people won't lose any data - `Alpha` if your software is still experimental - - `Obsolete` if your software is no longer maintaines + - `Obsolete` if your software is no longer maintained - `featured` should be left to false. We are working on [processes to formalise which project should be featured or not](https://github.com/matrix-org/matrix.org/issues/1584). - For the `licence`, please use [one of the identifiers listed by the SPDX](https://spdx.org/licenses/) - All of the properties under `extra.packages` are optional: only add the installation methods your project supports! From 407e52fe7cc0d9484a6a39447876adcf3023438f Mon Sep 17 00:00:00 2001 From: Thib Date: Wed, 31 Jan 2024 16:55:13 +0100 Subject: [PATCH 05/16] Add basic CONTRIBUTING.md --- CONTRIBUTING.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 919202ebd..5dba74758 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,4 +56,30 @@ If you agree to this for your contribution, then all that's needed is to include Signed-off-by: Your Name ``` -Git allows you to add this signoff automatically when using the `-s` flag to `git commit`, which uses the name and email set in your `user.name` and `user.email` git configs. \ No newline at end of file +Git allows you to add this signoff automatically when using the `-s` flag to `git commit`, which uses the name and email set in your `user.name` and `user.email` git configs. + +## What we are trying to achieve + +The Matrix Foundation is in charge of various activities revolving around Matrix. One of the most important activities to make Matrix a mainstream protocol is lowering the barrier to entry for the general public. The Matrix.org website is a critical step of the onboarding: this is what people will stumble upon when they look up “what is Matrix chat” or “chatting on Matrix” in a search engine. + +**The primary mission of the matrix.org website is to onboard various populations on Matrix, and turn them into supporters of the project.** + +We identified 4 different kind of populations that we want to address with the Matrix.org website. + +- **Everyday people** who want to use Matrix for instant messaging with family and friends. They are not tech savvy and just want simple steps to follow, and something that "just works™". They don't particularly care about Matrix. They could use WhatsApp or Signal. +- **Community managers** who want to find a platform for their community to talk on. They could use Slack or Discord. +- **Developers** who want to create clients, servers, bridges or bots. They are tech literate and are interested in how things work from a technical perspective. They are already convinced Matrix is useful and want either to create toys for it, or Matrix-based tools for production. +- **Entrepreneurs** who were told about Matrix and who need to see how it can bring value to them to create products based on Matrix. + +## How we measure progress + +The tools we have at our disposal are: + +- Privacy-preserving analytics with Plausible.io ([rationale here](https://ergaster.org/posts/2024/01/24-tracking-what-works/)). They allow us to track which are the most popular pages, custom events (e.g. to track if a call to action is often clicked on or not), and funnels +- User feedback, which will necessarily suffer the survivor bias + +## How we take decisions + +## How to open an useful issue + +## How to make sure your PR is reviewed From ddd50bf63c783fa50e540556f48bc7746336320d Mon Sep 17 00:00:00 2001 From: Thib Date: Wed, 7 Feb 2024 13:51:31 +0100 Subject: [PATCH 06/16] Update CONTRIBUTING --- CONTRIBUTING.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5dba74758..68f02873c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,6 +80,10 @@ The tools we have at our disposal are: ## How we take decisions -## How to open an useful issue +We try to keep a paper trail for all the decisions and implementation: -## How to make sure your PR is reviewed +- All of the changes on the website happen [through a Pull Request](https://github.com/matrix-org/matrix.org/pulls) +- Pull Requests should fix a documented and accepted [issue](https://github.com/matrix-org/matrix.org/pulls) +- Issues are reviewed by the maintainers of the project (@thibaultamartin and @MTRNord as of now). Some discussion can happen in [#matrix.org-website:matrix.org](https://matrix.to/#/%23matrix.org-website:matrix.org) but all decisions are logged in the issues themselves. + +We keep this paper trail to avoid having to review Pull Requests "fixing" things we don't need or want to be fixed. Of course we try to remain flexible where it makes sense, but want to stick to this process as much as possible. From 0451870f0fee292bd36f8565b33c601c76772179 Mon Sep 17 00:00:00 2001 From: Marcel Radzio Date: Thu, 21 Nov 2024 15:04:42 +0100 Subject: [PATCH 07/16] Make Contributing markdown more precise and add Bridges section in CONTENT.md. Also update the requirements around links and images --- CONTENT.md | 61 +++++++++++++++++++++++++++++++++++++++++-------- CONTRIBUTING.md | 6 +++-- 2 files changed, 56 insertions(+), 11 deletions(-) diff --git a/CONTENT.md b/CONTENT.md index ae9cbc2de..8cd4c79ca 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -1,16 +1,18 @@ +# How Content works on matrix.org + The matrix.org website is powered by [Zola](https://www.getzola.org/), a [static site generator](https://en.wikipedia.org/wiki/Static_site_generator). It ingests content in rather human-friendly formats, and turns it into the beautiful matrix.org website we all love. The format you need to use depends on the type of content you want to add. This documentation is about helping you create new content that the static site generator will accept. To get your content actually deploy on matrix.org, you need to be familiar with git, GitHub and Pull Requests. If that's not the case, we suggest either finding someone who is and can help, or dropping us a line in the [Matrix.org Website chat room](https://matrix.to/#/#matrix.org-website:matrix.org). ## Publishing to the blog -Articles on the blog are written in the markdown format. Markdown should generally be the same everywhere, but there are small variations around what you can or can't do with it. Zola supports the [CommonMark variant](https://commonmark.org/help/) of Markdown. +Articles on the blog are written in the markdown format. Markdown should generally be the same everywhere, but there are small variations around what you can or can't do with it. Zola supports the [CommonMark variant](https://commonmark.org/help/) of Markdown. Note that Zola's Markdown parser is pedantic about links and requires to use `<>` around a link without title. All the blog posts are sorted in directories. They live in `/content/blog/YEAR/MONTH/`, with `YEAR` and `MONTH` being the year and month in digit format, e.g. [`/content/blog/2024/01/`](https://github.com/matrix-org/matrix.org/tree/main/content/blog/2024/01). One surprising bit about Zola is that both the `YEAR` (e.g. `2024`) and `MONTH` (e.g. `01`) need to have a `_index.md` with the following content to be rendered by the generator: -``` +```markdown +++ transparent = true render = false @@ -24,7 +26,7 @@ In the frontmatter, make sure to format the date as `year-month-day` (e.g. `2024 You can use the following template to create a new blog post: -``` +```markdown +++ date = "2024-01-22T12:30:00Z" title = "Exciting news from the Foundation!" @@ -45,11 +47,16 @@ We are privacy-centric and don't want to track people individually, but we want ### Adding pictures in your post -It is possible to add pictures to your posts in markdown. First you need to drop the pictures in [`/static/blog/img`](https://github.com/matrix-org/matrix.org/tree/main/static/blog/img). Then, in the markdown file itself add the following line +It is possible to add pictures to your posts in markdown. First you need to drop the pictures in [`/static/blog/img`](https://github.com/matrix-org/matrix.org/tree/main/static/blog/img). Then, in the markdown file itself add the following lines +```jinja +{{ figure( + img="/blog/img/your-picture-name.png" + caption="A description of the picture") +}} ``` -![A description of the picture](/blog/img/your-picture-name.png) -``` + +This so called shortcode ensures that images have a consistent look across posts. ### Embedding a YouTube player @@ -61,7 +68,7 @@ Copy the series of characters after the `v=` and before the first `&` that you m In your markdown file, add this line to embed the YouTube player in a way that respects the user consent. -``` +```jinja {{ youtube_player(video_id="S1nBXjWWHoU") }} ``` ### Adding a picture for the socials @@ -70,7 +77,7 @@ You know the cool previews that are generated on socials (Mastodon, LinkedIn, an If you want to add your own, drop it in the PNG format in [`/static/blog/img`](https://github.com/matrix-org/matrix.org/tree/main/static/blog/img), and add the following lines to your frontmatter (between the two rows of `+++`): -``` +```toml [extra] image = "https://matrix.org/blog/img/YOUR-IMAGE.png" ``` @@ -85,7 +92,7 @@ Matrix clients are listed in [`/content/ecosystem/clients`](https://github.com/m To add a client, add your client's logo (ideally in SVG format) as `your-client-name.svg` and a markdown file as `your-client-name.md` file (no space allowed in the file name) under [`/content/ecosystem/clients`](https://github.com/matrix-org/matrix.org/tree/main/content/ecosystem/clients) and fill it with the following template: -``` +```markdown +++ title = "My client name" template = "ecosystem/client.html" @@ -130,8 +137,44 @@ Supercharge your communications with Example Client. - `featured` should be left to false. We are working on [processes to formalise which project should be featured or not](https://github.com/matrix-org/matrix.org/issues/1584). - For the `licence`, please use [one of the identifiers listed by the SPDX](https://spdx.org/licenses/) - All of the properties under `extra.packages` are optional: only add the installation methods your project supports! + - In case your option is not available please let us know by opening an issue. + ### Bridges +The Matrix Bridges are listed in [`/content/ecosystem/bridges`](https://github.com/matrix-org/matrix.org/tree/main/content/ecosystem/bridges). Inside of the folder you will find a folder for each third-party network. Within each network you can find a `bridges.toml` file which contains the information about individual bridges for the third-party network. + +To add a bridge, add the following template to the `bridges.toml` for the respective third-party network: + +```toml +[[bridges]] +name = "My bridge name" +maintainer = "Your name or organisation" +summary = """ +A short description about your bridge +""" + +maturity = "PICK ONE" Stable OR Beta OR Alpha OR Obsolete" +language = "PICK ONE (please check for existing languages to avoid using different names)" +license = "PICK ONE" +docs = "https://docs.mybridge.example.com" +repo = "https://github.com/example-org/example-repo" +room = "#your-matrix-room:example.com" +featured = false # Keep this as false. This will be handled by the repo maintainers +privilege.platform = "User" # Who can use/add the bridge on the third-party platform +privilege.matrix = "Homeserver Admin" # Any of Homeserver Admin, Room Admin, None + +# This can vary based on the network. Use Matrix terms here. When in doubt stick to this list. +[bridges.supports] +dm = true +groups = true +message_media = true +mentions = true +redactions = true +reactions = true +typing_notifications = true +read_receipts = true +``` + ### Servers ### Integrations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68f02873c..6ca4e4519 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,8 +82,10 @@ The tools we have at our disposal are: We try to keep a paper trail for all the decisions and implementation: -- All of the changes on the website happen [through a Pull Request](https://github.com/matrix-org/matrix.org/pulls) -- Pull Requests should fix a documented and accepted [issue](https://github.com/matrix-org/matrix.org/pulls) +- All of the changes on the website nees to happen [through a Pull Request](https://github.com/matrix-org/matrix.org/pulls) + - The only exception to this rules are if we broke things preventing our usual workflow. +- Pull Requests which do changes to existing content or add content outside of the blog should fix a documented and accepted [issue](https://github.com/matrix-org/matrix.org/pulls) - Issues are reviewed by the maintainers of the project (@thibaultamartin and @MTRNord as of now). Some discussion can happen in [#matrix.org-website:matrix.org](https://matrix.to/#/%23matrix.org-website:matrix.org) but all decisions are logged in the issues themselves. We keep this paper trail to avoid having to review Pull Requests "fixing" things we don't need or want to be fixed. Of course we try to remain flexible where it makes sense, but want to stick to this process as much as possible. + From a963873fa5338b5baaac492fde79a356928c11f9 Mon Sep 17 00:00:00 2001 From: Marcel Radzio Date: Thu, 21 Nov 2024 15:05:42 +0100 Subject: [PATCH 08/16] Fix typo --- CONTENT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTENT.md b/CONTENT.md index 8cd4c79ca..cb10acfda 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -99,7 +99,7 @@ template = "ecosystem/client.html" [extra] thumbnail = "your-client-name.svg" maintainer = "Your name or organisation" -maturity = "PICK ONE" Stable OR Beta OR Alpha OR Obsolete" +maturity = "PICK ONE Stable OR Beta OR Alpha OR Obsolete" repo = "https://github.com/example-org/example-repo" matrix_room = "#your-matrix-room:example.com" licence = "PICK ONE" @@ -153,7 +153,7 @@ summary = """ A short description about your bridge """ -maturity = "PICK ONE" Stable OR Beta OR Alpha OR Obsolete" +maturity = "PICK ONE Stable OR Beta OR Alpha OR Obsolete" language = "PICK ONE (please check for existing languages to avoid using different names)" license = "PICK ONE" docs = "https://docs.mybridge.example.com" From 15c122d067b05f7122bd289f11626da088f0691d Mon Sep 17 00:00:00 2001 From: Marcel Radzio Date: Thu, 21 Nov 2024 16:10:16 +0100 Subject: [PATCH 09/16] Add integrations and servers section. Also fix a typo --- CONTENT.md | 33 +++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 +- 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/CONTENT.md b/CONTENT.md index cb10acfda..a4cdd77ea 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -177,8 +177,41 @@ read_receipts = true ### Servers +Matrix Servers are listed in [`/content/ecosystem/servers/servers.toml`](https://github.com/matrix-org/matrix.org/blob/main/content/ecosystem/servers/servers.toml). Each entry is a new section in this toml file. + +To add a server, add the following template to the end of the `servers.toml` and edit it according to your server + +```toml +[[servers]] +name = "My Matrix Server" +description = "A Matrix server which can only reply status code 418" +author = "Your name or organisation" +maturity = "PICK ONE Stable OR Beta OR Alpha OR Obsolete" +language = "The programminglanguage of your server. For example 'Python'" +licence = "An spdx license code" +repository = "https://github.com/example-org/example-repo" +room = "#your-matrix-room:example.com" +``` + ### Integrations +Matrix integrations are listed in [`/content/ecosystem/integrations/integrations.toml`](https://github.com/matrix-org/matrix.org/blob/main/content/ecosystem/integrations/integrations.toml). A Matrix Integration can be for example a utility TUI but also Matrix Bots. Please see the description on the website itself to get a better feeling on the definition of Matrix Integrations. + +To add an integration, add the following template to the end of the `integrations.toml` and edit the fields according to your integration + +```toml +[[integrations]] +name = "My Matrix Integration" +description = "A brief description on which things it is able to do." +author = "Your name or organisation" +language = "The programminglanguage of your server. For example 'Python'" +licence = "An spdx license code" +repository = "https://github.com/example-org/example-repo" +room = "#your-matrix-room:example.com" +``` + +_Note that this section is due to further figuring out. See also _ + ### SDKs ### Hosting providers diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ca4e4519..e6c5d3b8b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,7 +82,7 @@ The tools we have at our disposal are: We try to keep a paper trail for all the decisions and implementation: -- All of the changes on the website nees to happen [through a Pull Request](https://github.com/matrix-org/matrix.org/pulls) +- All of the changes on the website need to happen [through a Pull Request](https://github.com/matrix-org/matrix.org/pulls) - The only exception to this rules are if we broke things preventing our usual workflow. - Pull Requests which do changes to existing content or add content outside of the blog should fix a documented and accepted [issue](https://github.com/matrix-org/matrix.org/pulls) - Issues are reviewed by the maintainers of the project (@thibaultamartin and @MTRNord as of now). Some discussion can happen in [#matrix.org-website:matrix.org](https://matrix.to/#/%23matrix.org-website:matrix.org) but all decisions are logged in the issues themselves. From 66e4f99db8296eab0d73b13c8fca2ca2f1b71d4e Mon Sep 17 00:00:00 2001 From: Marcel Radzio Date: Thu, 21 Nov 2024 16:34:26 +0100 Subject: [PATCH 10/16] Add sdks and hosting section. Also add some notes on prefered file formats of images --- CONTENT.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/CONTENT.md b/CONTENT.md index a4cdd77ea..cd42aaefc 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -51,13 +51,15 @@ It is possible to add pictures to your posts in markdown. First you need to drop ```jinja {{ figure( - img="/blog/img/your-picture-name.png" + img="/blog/img/your-picture-name.avif" caption="A description of the picture") }} ``` This so called shortcode ensures that images have a consistent look across posts. +We prefer using avif or webp files when possible. However if this is not an option we also accept PNG files provided they are reasonable sized and the file size is appropriate for web usage. + ### Embedding a YouTube player Embedding the YouTube Player loads cookies from youtube.com. This is fairly invasive in terms of privacy, and breaches the GDPR since we don't have a cookie banner to get visitor's consent to do so. @@ -82,6 +84,8 @@ If you want to add your own, drop it in the PNG format in [`/static/blog/img`](h image = "https://matrix.org/blog/img/YOUR-IMAGE.png" ``` +_Due to restrictions on the third-party consumers it is mandatory that we use PNG files here_ + ## Adding new projects to the ecosystem All of the ecosystem projects information are in subdirectories of [`/content/ecosystem`](https://github.com/matrix-org/matrix.org/tree/main/content/ecosystem/). @@ -214,8 +218,44 @@ _Note that this section is due to further figuring out. See also Date: Thu, 21 Nov 2024 16:47:48 +0100 Subject: [PATCH 11/16] Outline initial contribution guideline for documenttion pages --- CONTENT.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTENT.md b/CONTENT.md index cd42aaefc..b3b8eae54 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -258,5 +258,15 @@ It should NOT contain blatent marketing text. We hold the right to ask for rewor ## Adding documentation +Matrix.org provides a place to have documentation. Documentation is required to be on topic of the Matrix Protocol itself or how to get started using the protocol. + +We currently split the Documentation into these types: + +- Onboarding Documentation - Documentation for first time users +- Community Documenation - Documentation which we consider is helpful to run a good community using Matrix tools. This can include guideance on things like moderation or how Matrix features benefit Communities. +- Technical Documentation - Documentation that help people understanding to Matrix Protocol. This can range from a rough outline on how Matrix functions to guides on things like state resolution. + +Additionally to creating a documenation there comes a responsibility to the author. We require authors of a documentation page to be reachable or delegate a new contact point if they cant maintain it any further. We will tr at least once per year to reach out to an author to verify a documenation is still accurate. This may happen more often when we notice ourself that the documentation is likely stale. If there hasn't been a reply in a reasonable timeframe we hold the right to archive a documenation page without further warning as we cannot verify all documentation on a technical level. Therefor we rather list up to date maintained documentation rather than possibly stale documentation. These archived documentations can then be found at the [Older Documentation Section](https://matrix.org/docs/older/#all-past-documentation). + ## Adding sponsors From fb661de657a3b6c80efbd0e48ac852e740a98577 Mon Sep 17 00:00:00 2001 From: Marcel Radzio Date: Thu, 28 Nov 2024 14:05:21 +0100 Subject: [PATCH 12/16] Fix typos --- CONTENT.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTENT.md b/CONTENT.md index b3b8eae54..4ad23c3ae 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -252,7 +252,7 @@ website = "https://example.com" operating_since = "2018" description = """ What the service provides and any noteworthy limitations or features. -It should NOT contain blatent marketing text. We hold the right to ask for rewording it or reject it. +It should NOT contain blatant marketing text. We hold the right to ask for rewording it or reject it. """ ``` @@ -263,10 +263,10 @@ Matrix.org provides a place to have documentation. Documentation is required to We currently split the Documentation into these types: - Onboarding Documentation - Documentation for first time users -- Community Documenation - Documentation which we consider is helpful to run a good community using Matrix tools. This can include guideance on things like moderation or how Matrix features benefit Communities. +- Community Documentation - Documentation which we consider is helpful to run a good community using Matrix tools. This can include guidance on things like moderation or how Matrix features benefit Communities. - Technical Documentation - Documentation that help people understanding to Matrix Protocol. This can range from a rough outline on how Matrix functions to guides on things like state resolution. -Additionally to creating a documenation there comes a responsibility to the author. We require authors of a documentation page to be reachable or delegate a new contact point if they cant maintain it any further. We will tr at least once per year to reach out to an author to verify a documenation is still accurate. This may happen more often when we notice ourself that the documentation is likely stale. If there hasn't been a reply in a reasonable timeframe we hold the right to archive a documenation page without further warning as we cannot verify all documentation on a technical level. Therefor we rather list up to date maintained documentation rather than possibly stale documentation. These archived documentations can then be found at the [Older Documentation Section](https://matrix.org/docs/older/#all-past-documentation). +Additionally to creating a documentation there comes a responsibility to the author. We require authors of a documentation page to be reachable or delegate a new contact point if they cant maintain it any further. We will tr at least once per year to reach out to an author to verify a documentation is still accurate. This may happen more often when we notice ourself that the documentation is likely stale. If there hasn't been a reply in a reasonable timeframe we hold the right to archive a documentation page without further warning as we cannot verify all documentation on a technical level. Therefor we rather list up to date maintained documentation rather than possibly stale documentation. These archived documentations can then be found at the [Older Documentation Section](https://matrix.org/docs/older/#all-past-documentation). ## Adding sponsors From 2de2a09ca689856d9d7b0c101143a80edf939ad5 Mon Sep 17 00:00:00 2001 From: Marcel Radzio Date: Thu, 28 Nov 2024 14:24:13 +0100 Subject: [PATCH 13/16] Extend the docs for the documentation --- CONTENT.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/CONTENT.md b/CONTENT.md index 4ad23c3ae..b9480b0dd 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -268,5 +268,13 @@ We currently split the Documentation into these types: Additionally to creating a documentation there comes a responsibility to the author. We require authors of a documentation page to be reachable or delegate a new contact point if they cant maintain it any further. We will tr at least once per year to reach out to an author to verify a documentation is still accurate. This may happen more often when we notice ourself that the documentation is likely stale. If there hasn't been a reply in a reasonable timeframe we hold the right to archive a documentation page without further warning as we cannot verify all documentation on a technical level. Therefor we rather list up to date maintained documentation rather than possibly stale documentation. These archived documentations can then be found at the [Older Documentation Section](https://matrix.org/docs/older/#all-past-documentation). -## Adding sponsors +### What we expect from Documentation contributions + +Documentation on matrix.org should be documentation which is part of the 3 categories we defined above. If you think that there is a category missing then please first open an issue for us to discuss this. + +The Documentation is expected to have a writing style. This means specifically that we expect the documentation to be written in a neutral and personal tone. This means we prefer "To do X you want to do Y" over "To get to X one should do Y". Additionally to the tone we also expect a documentation page to be structured. think about headers to use which guide the reader and make it easy to find a section in the document. + +Last but not least we would like to have graphics in our documentation when it makes sense for the documentation. Specifically for Onboarding and Community Documentation this helps readers to imagine things more easily. For technical documentation however this is not always possible and is ok. However complicated flows should contain visualizations of this to help readers understand it. + +We are happy to review your documentation contributions and help you with any quetions that you may end up with. From a1006c342c38a1dca2135f5778cf23cec10608bd Mon Sep 17 00:00:00 2001 From: Marcel Radzio Date: Thu, 28 Nov 2024 14:36:11 +0100 Subject: [PATCH 14/16] Fix a typo --- CONTENT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTENT.md b/CONTENT.md index b9480b0dd..cb297cfa3 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -276,5 +276,5 @@ The Documentation is expected to have a writing style. This means specifically t Last but not least we would like to have graphics in our documentation when it makes sense for the documentation. Specifically for Onboarding and Community Documentation this helps readers to imagine things more easily. For technical documentation however this is not always possible and is ok. However complicated flows should contain visualizations of this to help readers understand it. -We are happy to review your documentation contributions and help you with any quetions that you may end up with. +We are happy to review your documentation contributions and help you with any questions that you may end up with. From 3fe84d0e0ae72ea3840d122c5135b82a4e0463d1 Mon Sep 17 00:00:00 2001 From: MTRNord Date: Sat, 14 Dec 2024 14:35:04 +0100 Subject: [PATCH 15/16] Add insert_anchor_links to the _index template --- CONTENT.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/CONTENT.md b/CONTENT.md index cb297cfa3..f66798e45 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -16,6 +16,7 @@ One surprising bit about Zola is that both the `YEAR` (e.g. `2024`) and `MONTH` +++ transparent = true render = false +insert_anchor_links = "left" +++ ``` @@ -73,6 +74,7 @@ In your markdown file, add this line to embed the YouTube player in a way that r ```jinja {{ youtube_player(video_id="S1nBXjWWHoU") }} ``` + ### Adding a picture for the socials You know the cool previews that are generated on socials (Mastodon, LinkedIn, and others) when you paste a link? Matrix.org supports them! By default if you don't specify any, it is going to use [this placeholder](https://github.com/matrix-org/matrix.org/blob/main/static/blog/img/matrix-logo.png) image. @@ -134,14 +136,14 @@ Supercharge your communications with Example Client. ``` - For the `maturity`, please pick one of - - `Stable` if your software has been running in production for a little while and if you are confident in the sustainability of the project - - `Beta` if there are rough edges but people won't lose any data - - `Alpha` if your software is still experimental - - `Obsolete` if your software is no longer maintained + - `Stable` if your software has been running in production for a little while and if you are confident in the sustainability of the project + - `Beta` if there are rough edges but people won't lose any data + - `Alpha` if your software is still experimental + - `Obsolete` if your software is no longer maintained - `featured` should be left to false. We are working on [processes to formalise which project should be featured or not](https://github.com/matrix-org/matrix.org/issues/1584). - For the `licence`, please use [one of the identifiers listed by the SPDX](https://spdx.org/licenses/) - All of the properties under `extra.packages` are optional: only add the installation methods your project supports! - - In case your option is not available please let us know by opening an issue. + - In case your option is not available please let us know by opening an issue. ### Bridges @@ -254,7 +256,7 @@ description = """ What the service provides and any noteworthy limitations or features. It should NOT contain blatant marketing text. We hold the right to ask for rewording it or reject it. """ -``` +``` ## Adding documentation @@ -277,4 +279,3 @@ The Documentation is expected to have a writing style. This means specifically t Last but not least we would like to have graphics in our documentation when it makes sense for the documentation. Specifically for Onboarding and Community Documentation this helps readers to imagine things more easily. For technical documentation however this is not always possible and is ok. However complicated flows should contain visualizations of this to help readers understand it. We are happy to review your documentation contributions and help you with any questions that you may end up with. - From 61154ba750944a8e4052908d39dd42f7313c7f00 Mon Sep 17 00:00:00 2001 From: MTRNord Date: Sat, 14 Dec 2024 14:40:00 +0100 Subject: [PATCH 16/16] Apply the requested changes --- CONTENT.md | 38 ++++++++++++++++++-------------------- CONTRIBUTING.md | 3 +-- 2 files changed, 19 insertions(+), 22 deletions(-) diff --git a/CONTENT.md b/CONTENT.md index f66798e45..1be8d68b9 100644 --- a/CONTENT.md +++ b/CONTENT.md @@ -57,7 +57,7 @@ It is possible to add pictures to your posts in markdown. First you need to drop }} ``` -This so called shortcode ensures that images have a consistent look across posts. +This shortcode ensures that images have a consistent look across posts. We prefer using avif or webp files when possible. However if this is not an option we also accept PNG files provided they are reasonable sized and the file size is appropriate for web usage. @@ -86,7 +86,7 @@ If you want to add your own, drop it in the PNG format in [`/static/blog/img`](h image = "https://matrix.org/blog/img/YOUR-IMAGE.png" ``` -_Due to restrictions on the third-party consumers it is mandatory that we use PNG files here_ +_Due to restrictions on the third-party consumers it is mandatory that we use PNG files here._ ## Adding new projects to the ecosystem @@ -108,7 +108,7 @@ maintainer = "Your name or organisation" maturity = "PICK ONE Stable OR Beta OR Alpha OR Obsolete" repo = "https://github.com/example-org/example-repo" matrix_room = "#your-matrix-room:example.com" -licence = "PICK ONE" +licence = "PICK ONE identifier from https://spdx.org/licenses/" latest_release = "2022-11-02" featured = false @@ -136,14 +136,14 @@ Supercharge your communications with Example Client. ``` - For the `maturity`, please pick one of - - `Stable` if your software has been running in production for a little while and if you are confident in the sustainability of the project - - `Beta` if there are rough edges but people won't lose any data - - `Alpha` if your software is still experimental - - `Obsolete` if your software is no longer maintained + - `Stable` if your software has been running in production for a little while and if you are confident in the sustainability of the project + - `Beta` if there are rough edges but people won't lose any data + - `Alpha` if your software is still experimental + - `Obsolete` if your software is no longer maintained - `featured` should be left to false. We are working on [processes to formalise which project should be featured or not](https://github.com/matrix-org/matrix.org/issues/1584). - For the `licence`, please use [one of the identifiers listed by the SPDX](https://spdx.org/licenses/) - All of the properties under `extra.packages` are optional: only add the installation methods your project supports! - - In case your option is not available please let us know by opening an issue. + - In case your option is not available please let us know by opening an issue. ### Bridges @@ -161,7 +161,7 @@ A short description about your bridge maturity = "PICK ONE Stable OR Beta OR Alpha OR Obsolete" language = "PICK ONE (please check for existing languages to avoid using different names)" -license = "PICK ONE" +license = "PICK ONE identifier from https://spdx.org/licenses/" docs = "https://docs.mybridge.example.com" repo = "https://github.com/example-org/example-repo" room = "#your-matrix-room:example.com" @@ -193,8 +193,8 @@ name = "My Matrix Server" description = "A Matrix server which can only reply status code 418" author = "Your name or organisation" maturity = "PICK ONE Stable OR Beta OR Alpha OR Obsolete" -language = "The programminglanguage of your server. For example 'Python'" -licence = "An spdx license code" +language = "The programming language of your server. For example 'Python'" +licence = "PICK ONE identifier from https://spdx.org/licenses/" repository = "https://github.com/example-org/example-repo" room = "#your-matrix-room:example.com" ``` @@ -211,7 +211,7 @@ name = "My Matrix Integration" description = "A brief description on which things it is able to do." author = "Your name or organisation" language = "The programminglanguage of your server. For example 'Python'" -licence = "An spdx license code" +licence = "PICK ONE identifier from https://spdx.org/licenses/" repository = "https://github.com/example-org/example-repo" room = "#your-matrix-room:example.com" ``` @@ -230,7 +230,7 @@ name = "My Matrix SDK" maintainer = "Your name or organisation" maturity = "PICK ONE Stable OR Beta OR Alpha OR Obsolete" language = "The programminglanguage of your server. For example 'Python'" -licence = "An spdx license code" +licence = "PICK ONE identifier from https://spdx.org/licenses/" repository = "github.com/example-org/example-repo" # In which type of application this SDK is meant to get used. This should be an array. # Possible values are "bridge", "bot", "client" @@ -254,7 +254,7 @@ website = "https://example.com" operating_since = "2018" description = """ What the service provides and any noteworthy limitations or features. -It should NOT contain blatant marketing text. We hold the right to ask for rewording it or reject it. +This page is meant to help end users find a hosting provider for their needs. For marketing opportunities, please reach out to managing-director@foundation.matrix.org """ ``` @@ -265,17 +265,15 @@ Matrix.org provides a place to have documentation. Documentation is required to We currently split the Documentation into these types: - Onboarding Documentation - Documentation for first time users -- Community Documentation - Documentation which we consider is helpful to run a good community using Matrix tools. This can include guidance on things like moderation or how Matrix features benefit Communities. +- Community Documentation - Documentation we consider helpful to run a healthy Matrix community. This includes guidance on moderation best practices, and how Matrix features benefit communities. - Technical Documentation - Documentation that help people understanding to Matrix Protocol. This can range from a rough outline on how Matrix functions to guides on things like state resolution. -Additionally to creating a documentation there comes a responsibility to the author. We require authors of a documentation page to be reachable or delegate a new contact point if they cant maintain it any further. We will tr at least once per year to reach out to an author to verify a documentation is still accurate. This may happen more often when we notice ourself that the documentation is likely stale. If there hasn't been a reply in a reasonable timeframe we hold the right to archive a documentation page without further warning as we cannot verify all documentation on a technical level. Therefor we rather list up to date maintained documentation rather than possibly stale documentation. These archived documentations can then be found at the [Older Documentation Section](https://matrix.org/docs/older/#all-past-documentation). +Creating a documentation comes with the responsibility to maintain it. We require authors of a documentation page to be reachable or delegate a new contact point if they cant maintain it any further. Obviously outdated documentation with unreachable authors will be listed in the [Older Documentation Section](https://matrix.org/docs/older/#all-past-documentation). ### What we expect from Documentation contributions -Documentation on matrix.org should be documentation which is part of the 3 categories we defined above. If you think that there is a category missing then please first open an issue for us to discuss this. - -The Documentation is expected to have a writing style. This means specifically that we expect the documentation to be written in a neutral and personal tone. This means we prefer "To do X you want to do Y" over "To get to X one should do Y". Additionally to the tone we also expect a documentation page to be structured. think about headers to use which guide the reader and make it easy to find a section in the document. +To keep documentation on matrix.org tidy and approachable, it needs to be sorted into one of the 3 categories defined above. If you think a new category is needed, please first open an issue so we can discuss it. -Last but not least we would like to have graphics in our documentation when it makes sense for the documentation. Specifically for Onboarding and Community Documentation this helps readers to imagine things more easily. For technical documentation however this is not always possible and is ok. However complicated flows should contain visualizations of this to help readers understand it. +Images make concepts easier to understand than walls of text. Screenshots make the documentation easier to follow in the onboarding and community sections. Diagrams and other illustrations can help break down more technical or complicated documentation. We are happy to review your documentation contributions and help you with any questions that you may end up with. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e6c5d3b8b..38aeae8ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,7 +60,7 @@ Git allows you to add this signoff automatically when using the `-s` flag to `gi ## What we are trying to achieve -The Matrix Foundation is in charge of various activities revolving around Matrix. One of the most important activities to make Matrix a mainstream protocol is lowering the barrier to entry for the general public. The Matrix.org website is a critical step of the onboarding: this is what people will stumble upon when they look up “what is Matrix chat” or “chatting on Matrix” in a search engine. +One key mission of the Foundation is to make Matrix a mainstream protocol. For this, onboarding needs to be made easy for new users. The Matrix.org website is a critical step in this journey: this is where people land when they look up "what is Matrix chat" or "chatting on Matrix" in a search engine. **The primary mission of the matrix.org website is to onboard various populations on Matrix, and turn them into supporters of the project.** @@ -88,4 +88,3 @@ We try to keep a paper trail for all the decisions and implementation: - Issues are reviewed by the maintainers of the project (@thibaultamartin and @MTRNord as of now). Some discussion can happen in [#matrix.org-website:matrix.org](https://matrix.to/#/%23matrix.org-website:matrix.org) but all decisions are logged in the issues themselves. We keep this paper trail to avoid having to review Pull Requests "fixing" things we don't need or want to be fixed. Of course we try to remain flexible where it makes sense, but want to stick to this process as much as possible. -