Merge pull request #1357 from inlang/markdown-refactor

refactor: markdown

.prettierrc.json

@@ -1,6 +1,5 @@
 {
 	"semi": false,
 	"useTabs": true,
-	"trailingComma": "all",
 	"printWidth": 100
 }

inlang/blog/git-as-sdk.md

@@ -1,10 +1,4 @@
----
-title: What if a Git SDK to build apps exists?
-href: /blog/git-as-sdk
-description: Git as a backend and content database might be superior to database driven solutions for apps like Figma, Google Docs, & Co.
----
-
-# {% $frontmatter.title %}
+# What if a Git SDK to build apps exists?
 
 While exploring how to design a developer-first localization solution (also known as i18n, aka offering software in different human languages), I realized that git as a backend might be superior to database driven solutions for applications like Figma, Google Docs, & Co. I refer to a cloud-based backend as a backend where users operate on documents that are stored in a database, opposed to documents in the form of files.
 

inlang/blog/inlang-refactor.md

@@ -1,10 +1,4 @@
----
-title: Refactoring Inlang
-href: /blog/refactoring-inlang
-description: Inlang got a major refactor which brings new capabilities to the ecosystem.
----
-
-# {% $frontmatter.title %}
+# Refactoring Inlang
 
 ![architecture inlang new](https://cdn.jsdelivr.net/gh/inlang/monorepo/inlang/documentation/assets/architecture.jpg)
 

inlang/blog/notes-on-git-based-architecture.md

@@ -1,10 +1,4 @@
----
-title: "March 2022: Does a git-based architecture make sense?"
-href: /blog/notes-on-git-based-architecture
-description: Internal notes from March 2022 on why a git-based architecture for localization and beyond seems to make sense.
----
-
-# {% $frontmatter.title %}
+# March 2022: Does a git-based architecture make sense?
 
 This document has been written by me, [@samuelstroschein](https://twitter.com/samuelstroschein), as a note to myself on why a git-based architecture makes sense.
 

inlang/blog/tableOfContents.json

@@ -1,6 +1,26 @@
 [
-	"./inlang-refactor.md",
-	"./the-next-git.md",
-	"./git-as-sdk.md",
-	"./notes-on-git-based-architecture.md"
+	{
+		"path": "./inlang-refactor.md",
+		"slug": "inlang-refactor",
+		"title": "Refactoring Inlang",
+		"description": "Inlang got a major refactor which brings new capabilities to the ecosystem."
+	},
+	{
+		"path": "./the-next-git.md",
+		"slug": "the-next-git",
+		"title": "The next git",
+		"description": "Git, or more generalized version control, seems to be an appropriate backend for content heavy apps."
+	},
+	{
+		"path": "./git-as-sdk.md",
+		"slug": "git-as-sdk",
+		"title": "What if a Git SDK to build apps exists?",
+		"description": "Git as a backend and content database might be superior to database driven solutions for apps like Figma, Google Docs, & Co."
+	},
+	{
+		"path": "./notes-on-git-based-architecture.md",
+		"slug": "notes-on-git-based-architecture",
+		"title": "March 2022: Does a git-based architecture make sense?",
+		"description": "Internal notes from March 2022 on why a git-based architecture for localization and beyond seems to make sense."
+	}
 ]

inlang/blog/the-next-git.md

@@ -1,20 +1,9 @@
----
-title: The next git
-href: /blog/the-next-git
-description: Git, or more generalized version control, seems to be an appropriate backend for content heavy apps.
----
-
-# {% $frontmatter.title %}
+# The next git
 
 **Inlang might bring version control to domains outside of software engineering.**
 
-{% Figure
-
-    src="https://cdn.jsdelivr.net/gh/inlang/monorepo/inlang/documentation/assets/what-if-1000-artists.jpeg"
-    alt="What if 1000s of artists are able to create a song together?"
-    caption="A slide from one of the first presentations about inlang being built on git, and the possibilities version control might open. The image has been taken from the iconic iPod campaign."
-
-/%}
+<display-figure src="https://cdn.jsdelivr.net/gh/inlang/monorepo/inlang/documentation/assets/what-if-1000-artists.jpeg" alt="What if 1000s of artists are able to create a song together?" caption="What if 1000s of artists are able to create a song together?"
+    caption="A slide from one of the first presentations about inlang being built on git, and the possibilities version control might open. The image has been taken from the iconic iPod campaign."></display-figure>
 
 Inlang is git-based localization infrastructure and, simultaneously, a case study for version control-based applications. Git provides unprecedented (async) collaboration, automation, and simple review flows out of the box. Wouldn't version control be benefitial to domains outside of software engineering? What if artists could collaborate on a song in the way software engineers collaborate on open source software? What if open source mechanical engineering would be as common as open source software? What if... version control enables new workflows and apps with built-in version control are better than their counterparts?
 

inlang/documentation/concept/app.md

@@ -1,12 +1,6 @@
----
-title: App
-href: /documentation/app
-description: An inlang app provides a user interface for a project.
----
+# App
 
-# {% $frontmatter.title %}
-
-{% $frontmatter.description %} A wide variety of apps for many different use-cases exists. Go to the [marketplace](/marketplace) to find apps that fit your needs.
+An inlang app provides a user interface for a project. A wide variety of apps for many different use-cases exists. Go to the [marketplace](/marketplace) to find apps that fit your needs.
 
 ![inlang app concept](https://cdn.jsdelivr.net/gh/inlang/monorepo/inlang/documentation/assets/app.jpg)
 

inlang/documentation/concept/language-tag.md

@@ -1,10 +1,4 @@
----
-title: Language tag
-href: /documentation/language-tag
-description: TODO TODO TODO TODO TODO
----
-
-# {% $frontmatter.title %}
+# Language tag
 
 A language tag is a standardized code or tag that is used to identify human languages and regions.
 

inlang/documentation/concept/library.md

@@ -1,9 +1,3 @@
----
-title: Library
-href: /documentation/library
-description: Developers can use inlang libraries for their own software projects.
----
+# Library
 
-# {% $frontmatter.title %}
-
-{% $frontmatter.description %} A wide variety of libraries for different use-cases exists. Go to the [marketplace](/marketplace) to find a library that fit your needs.
+Developers can use inlang libraries for their own software projects. A wide variety of libraries for different use-cases exists. Go to the [marketplace](/marketplace) to find a library that fit your needs.

inlang/documentation/concept/lint-rule.md

@@ -1,12 +1,6 @@
----
-title: Lint rule
-href: /documentation/lint-rule
-description: Lint rules validate messages and other types of content in an inlang project.
----
+# Lint rule
 
-# {% $frontmatter.title %}
-
-{% $frontmatter.description %}
+Lint rules validate messages and other types of content in an inlang project.
 
 For example, the [missing translation lint rule](/marketplace/messageLintRule.inlang.missingTranslation) reports an issue if a message is missing a translation for a specified [language tag](/documentation/concepts/language-tag). Inlang applications use lint rules to validate content and report issues to the user.
 

inlang/documentation/concept/message.md

@@ -1,10 +1,4 @@
----
-title: Message
-href: /documentation/message
-description: TODO TODO TODO TODO TODO
----
-
-# {% $frontmatter.title %}
+# Message
 
 A message is a piece of text that is displayed to the user. Everything within an application, like the text on a button, is a message. A message itself is composed of variants. User preferences like language or region determine which variant is displayed. Inlang's message handling is based on the [ICU Message Format 2.0](https://github.com/unicode-org/message-format-wg/blob/main/spec/syntax.md).
 

inlang/documentation/concept/plugin.md

@@ -1,12 +1,6 @@
----
-title: Plugin
-href: /documentation/plugin
-description: An inlang plugin defines and extend how an inlang app should behave.
----
+# Plugin
 
-# {% $frontmatter.title %}
-
-{% $frontmatter.description %}
+An inlang plugin defines and extend how an inlang app should behave.
 
 For example, plugin A defines that [messages](/documentation/message) should be stored in a database, while plugin B defines that messages should be stored in a file. An [inlang app](/documentation/app) that uses plugin A will store messages in a database, while an inlang app that uses plugin B will store messages in a file.
 

inlang/documentation/concept/project.md

@@ -1,10 +1,4 @@
----
-title: Project
-href: /documentation/project
-description: TODO TODO TODO TODO TODO
----
-
-# {% $frontmatter.title %}
+# Project
 
 An inlang project is defined by a file that is named `project.inlang.json`. The file contains the settings for a project and is the entrypoint for all applications, plugins, and tools in the inlang ecosystem.
 

inlang/documentation/guide/develop-app.md

@@ -1,10 +1,4 @@
----
-title: Develop an app
-href: /documentation/develop-app
-description: How to develop an inlang-based app.
----
-
-# {% $frontmatter.title %}
+# Develop an app
 
 There are many ways users interact with inlang. This documentation gives you information on how to develop your own inlang-based app.
 
@@ -31,7 +25,7 @@ In your app's `marketplace-manifest.json` make sure to define the following info
 |----------------------|---------------------------------------------------------------|
 | `id`                 | Unique identifier for your app.                         |
 | `icon`        | Link to the icon of your app (optional).              |
-| `coverImage`        | Optional cover image acting as preview of your app.              |
+| `gallery`        | Optional gallery, the first image acts as coverImage for your app.              |
 | `displayName`        | A user-friendly display name for your app.              |
 | `description`        | Briefly describe what your app does.              |
 | `readme`             | Link to the README documentation for your app.          |

inlang/documentation/guide/develop-lint-rule.md

@@ -1,10 +1,4 @@
----
-title: Develop a lint rule
-href: /documentation/develop-lint-rule
-description: Create an own lint rule for inlang projects.
----
-
-# {% $frontmatter.title %}
+# Develop a lint rule
 
 This documentation provides step-by-step instructions on developing a lint rule for the inlang ecosystem. Lint rules are used to check for specific patterns or issues in translated messages to ensure high-quality translations. Follow the guide below to create your own custom lint rule.
 
@@ -59,7 +53,7 @@ In your lint rule's `marketplace-manifest.json` make sure to define the followin
 |----------------------|---------------------------------------------------------------|
 | `id`                 | Unique identifier for your lint rule.                         |
 | `icon`        | Link to the icon of your lint rule (optional).              |
-| `coverImage`        | Optional cover image acting as preview of your lint rule.              |
+| `gallery`        | Optional gallery, the first image acts as coverImage for your lint rule.              |
 | `displayName`        | A user-friendly display name for your lint rule.              |
 | `description`        | Briefly describe what your lint rule checks for.              |
 | `readme`             | Link to the README documentation for your lint rule.          |

inlang/documentation/guide/develop-plugin.md

@@ -1,10 +1,4 @@
----
-title: Develop a plugin
-href: /documentation/develop-plugin
-description: Learn how easy it is to write your own plugin for inlang projects.
----
-
-# {% $frontmatter.title %}
+# Develop a plugin
 
 Plugins are a powerful way to extend the functionality of inlang applications. This documentation provides you with the information you need to develop your own plugin.
 
@@ -60,7 +54,7 @@ In your lint rule's `marketplace-manifest.json` make sure to define the followin
 |----------------------|---------------------------------------------------------------|
 | `id`                 | Unique identifier for your plugin.                         |
 | `icon`        | Link to the icon of your plugin (optional).              |
-| `coverImage`        | Optional cover image acting as preview of your plugin.              |
+| `gallery`        | Optional gallery, the first image acts as coverImage for your plugin.              |
 | `displayName`        | A user-friendly display name for your plugin.              |
 | `description`        | Briefly describe what your plugin does.              |
 | `readme`             | Link to the README documentation for your plugin.          |

inlang/documentation/guide/publish-marketplace.md

@@ -1,10 +1,4 @@
----
-title: Publish to the marketplace
-href: /documentation/publish-marketplace
-description: Reach more of your target audience by publishing your app, plugin, or lint rule to the marketplace.
----
-
-# {% $frontmatter.title %}
+# Publish to the marketplace
 
 Publishing your own plugin or lint rule to the [marketplace](/marketplace) is straightforward, as the only thing you have to add to our item registry is the URL of your `marketplace-manifest.json`.
 
@@ -35,9 +29,25 @@ You can ensure that your manifest is valid by loading the following schema.
 | `id`                 | The unique identifier should always be written in camelCase like this: `camelCase.camelCase.camelCase`                         |
 | `displayName`                 | Please follow the [Apple Style Guide](https://support.apple.com/de-de/guide/applestyleguide/apsgb744e4a3/web) and write the first letter of a new word in the title always in uppercase, e.g. `Language Tag`. **Rule of thumb:** The first letter of the first word always has to be uppercase, except your displayName is a name written in lowercase letters everywhere else like `npm` for example.                       |
 | `description`                 | Please make sure to describe your item as simple as possible. It is best practice to write 100 to 200 characters.                         |
-`readme`                 | The readme acts as documentation for your item and is written in markdown.                         |
+`readme`                 | The readme acts as documentation for your item and is written in markdown. Feel free to use github flavored markdown, additionally you use inlang's custom web components (doc-elements).                      |
 `keywords`                 | Keywords are always written in lowercase e.g. `i18n`, `adoptable` …                          |
 
+#### Custom web components
+
+| Element        | Attribute   | Description                                                | Required |
+|----------------|-------------|------------------------------------------------------------|----------|
+| `<doc-figure>` | src         | Source to the image file.                                  | Yes      |
+|                | alt         | Alternative text for screen readers.                       | Yes      |
+|                | caption     | Caption shown below the image.                             | Yes      |
+| `<doc-icon>`   | icon        | [Iconify](https://icon-sets.iconify.design/) icon tag.     | Yes      |
+|                | size        | The size of the icon.                                      | Yes      |
+| `<doc-link>`   | title       | The title for the document link.                           | Yes      |
+|                | icon        | [Iconify](https://icon-sets.iconify.design/) icon tag.     | Yes      |
+|                | href        | The link behind the document link.                         | Yes      |
+|                | description | The description shown in the quick link.                   | Yes      |
+
+This format reduces repetition by listing common attributes for each element under the respective element's section.
+
 ### 2. Add the link to your marketplace manifest to the registry
 
 Add the raw link of your manifest to [this file](https://github.com/inlang/monorepo/blob/main/inlang/source-code/marketplace-registry/registry.json). You can fork the repository to do so.

inlang/documentation/overview/architecture.md

@@ -1,10 +1,4 @@
----
-title: Architecture
-href: /documentation/architecture
-description: TODO TODO TODO TODO TODO
----
-
-# {% $frontmatter.title %}
+# Architecture
 
 Inlang's architecture consists of four main components:
 

inlang/documentation/overview/introduction.md

@@ -1,56 +1,24 @@
----
-title: Introduction
-href: /documentation
-description: Inlang is globalization infrastructure that powers an ecosystem of apps, plugins, and solutions that make globalization simple.
----
-
-# {% $frontmatter.title %}
+# Introduction
 
 ## What is inlang?
 
-{% $frontmatter.description %}
+Inlang is globalization infrastructure that powers an ecosystem of apps, plugins, and solutions that make globalization simple.
 
 ![inlang ecosystem](https://cdn.jsdelivr.net/gh/inlang/monorepo/inlang/documentation/assets/ecosystem.jpg)
 
 ### Infrastructure approach
 
 For every use case, there is an app, a plugin, a lint rule, or a custom solution that can be built. Inlang's infrastructure powers an ecosystem of tools, applications, best practices, and automations for organizations to go global.
 
-{% Figure
-src="https://cdn.jsdelivr.net/gh/inlang/monorepo/inlang/documentation/assets/project.jpg"
-alt="one config file to power all infrastructure tools"
-caption="Sketch about the concept of one configuration file that powers all tools, automation, and applications for globalization that developers build on top of."
-
-/%}
+<doc-figure src="https://cdn.jsdelivr.net/gh/inlang/monorepo/inlang/documentation/assets/project.jpg" alt="one config file to power all infrastructure tools" caption="Sketch about the concept of one configuration file that powers all tools, automation, and applications for globalization that developers build on top of."></doc-figure>
 
 ### Version control and automation via CI/CD
 
 Inlang apps are built on lix. Lix is a git-compatible version control backend for applications. Using lix provides inlang with CI/CD for globalization and collaboration between developers, translators, and designers on one common source of truth: your repository and your data.
 
-{% Figure
-
-    src="https://github.com/inlang/monorepo/assets/58360188/917cc987-669d-4203-a2ed-8184087fd070"
-
-    alt="lix-based globalization infrastructure"
-
-    caption="Lix repositories act as building blocks for tools, applications like the editor, and automation via CI/CD."
-
-/%}
-
-{% QuickLinks %}
-
-    {% QuickLink
-        title="Getting started"
-        icon="fast"
-        href="/documentation/manually-create-project"
-        description="Create a new project."
-    /%}
-
-    {% QuickLink
-        title="Marketplace"
-        icon="add-plugin"
-        href="/marketplace"
-        description="Find apps, plugins, and lint rules."
-    /%}
+<doc-figure src="https://github.com/inlang/monorepo/assets/58360188/917cc987-669d-4203-a2ed-8184087fd070" alt="lix-based globalization infrastructure" caption="Lix repositories act as building blocks for tools, applications like the editor, and automation via CI/CD."></doc-figure>
 
-{% /QuickLinks %}
+<doc-links>
+    <doc-link title="Getting started" icon="material-symbols:fast-forward-outline-rounded" href="/documentation/manually-create-project" description="Create a new project."></doc-link>
+    <doc-link title="Marketplace" icon="material-symbols:add-business-outline-rounded" href="/marketplace" description="Find apps, plugins, and lint rules."></doc-link>
+</doc-links>

inlang/documentation/overview/manually-create-project.md

@@ -1,10 +1,4 @@
----
-title: Manually creating a new project
-href: /documentation/manually-create-project
-description: You can manually create a new project if inlang.com/new is not working for you.
----
-
-# {% $frontmatter.title %}
+# Manually creating a new project
 
 You can manually create a new project via the CLI or by creating an inlang project file.
 

inlang/documentation/reference/comver.md

@@ -1,10 +1,4 @@
----
-title: Backwards compatible versioning
-href: /documentation/comver
-description: You can manually create a new project if inlang.com/new is not working for you.
----
-
-# {% $frontmatter.title %}
+# Backwards compatible versioning
 
 > Is this update backwards compatible?