feat(homepage): enhance quick start with syntax highlighting and code annotations

angelo-v · angelo-v · commit cbdc390ffe4c · 2025-09-08T21:40:48.000+02:00
diff --git a/homepage/docs/getting-started/quick-start.md b/homepage/docs/getting-started/quick-start.md
@@ -2,12 +2,12 @@
 
 1. Create a plain old html file
 2. Add latest PodOS script tag and stylesheet to the head
-3. Add a <pos-app></pos-app> to the body and use any PodOS element within it.
-4. Host the page on any webserver (like your Solid Pod 😉)
+3. Add a `<pos-app></pos-app>` to the body and use any PodOS element within it.
+4. Host the page on any webserver (like your [Solid](../solid/index.md) Pod 😉)
 
 Try this 🤩:
 
-```html
+``` html linenums="1" hl_lines="5-12 15 16 17 19 22"
 <!DOCTYPE html>
 <html>
 <head>
@@ -19,25 +19,31 @@ Try this 🤩:
   <link
     href="https://cdn.jsdelivr.net/npm/@pod-os/elements/dist/elements/elements.css"
     rel="stylesheet"
-  />
+  />  <!-- (1)!  -->
 </head>
 <body>
-<pos-app> <!-- will provide a PodOS instance -->
+<pos-app> <!-- (2)!  -->
   <pos-resource
-    uri="https://solidproject.solidcommunity.net/profile/card#me"
-  > <!-- Loads the resource and sets the context for all the child elements -->
-    <h1> <!-- You can just combine normal HTML with PodOS elements -->
-      <pos-label /> <!-- renders a human-readable name of the resource -->
+    uri="https://solidproject.solidcommunity.net/profile/card#me"> <!-- (3)! --> 
+    <h1> <!-- (4)! -->
+      <pos-label /> <!-- (5)! -->
     </h1>
     <blockquote>
-      <pos-description /> <!-- renders a description of the resource -->
+      <pos-description /> <!-- (6)! -->
     </blockquote>
   </pos-resource>
 </pos-app>
 </body>
 </html>
 ```
 
+1. PodOS can be easily included from any CDN
+2. `<pos-app>` will provide PodOS to child elements. All other PodOS elements must be nested inside a `<pos-app>`
+3. Loads the resource and sets the context for all the child elements
+4. You can just combine normal HTML with PodOS elements
+5. `<pos-label` renders a human-readable name of the resource
+6. `<pos-description>` renders a renders a description of the resource
+
 Check out the [📖 Storybook documentation](https://pod-os.github.io/PodOS/storybook/) to learn about the available elements.
 
 Also, check out the [🧑‍🏫 tutorial section](../tutorials/index.md) on practical guides.
diff --git a/homepage/mkdocs.yml b/homepage/mkdocs.yml
@@ -19,6 +19,9 @@ theme:
     - navigation.tabs
     - navigation.footer
     - navigation.indexes
+    - content.code.copy
+    - content.code.select
+    - content.code.annotate
   logo: assets/logo.svg
   custom_dir: docs/overrides
   palette:
@@ -48,4 +51,11 @@ markdown_extensions:
   - md_in_html
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
