fix: file tree & automatic formatting (#60)

VGVentures · Aug 29, 2024 · 9f9f418 · 9f9f418
1 parent 7d5d4a4
commit 9f9f418
Show file tree

Hide file tree

Showing 6 changed files with 219 additions and 163 deletions.
diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml
@@ -0,0 +1,21 @@
+name: 🧼 Formatting
+
+on: push
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout your repository using git
+        uses: actions/checkout@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run Markdown Lint
+        run: npm run format:check
diff --git a/cspell.json b/cspell.json
@@ -1,17 +1,8 @@
 {
   "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
   "version": "0.2",
-  "ignorePaths": [
-    "node_modules/**",
-    ".**/"
-  ],
-  "files": [
-    "**/*.md",
-    "**/*.mdx",
-    "**/*.tsx",
-    "**/*.ts",
-    "**/*.json"
-  ],
+  "ignorePaths": ["node_modules/**", ".**/"],
+  "files": ["**/*.md", "**/*.mdx", "**/*.tsx", "**/*.ts", "**/*.json"],
   "words": [
     "ABAP",
     "Abuild",

diff --git a/src/content/docs/architecture/backend.md → src/content/docs/architecture/backend.mdx b/src/content/docs/architecture/backend.md → src/content/docs/architecture/backend.mdx
@@ -3,6 +3,8 @@ title: Backend Architecture
 description: Best practices for building backend APIs.
 ---
 
+import { FileTree } from "@astrojs/starlight/components";
+
 Loose coupling, separation of concerns and layered architecture should not only be applied to frontend development. These principles can also be applied during backend development. For example, concepts such as route navigation, data access, data processing and data models can be separated and tested in isolation.
 
 :::note
@@ -29,39 +31,40 @@ Putting the backend in the same repository as the frontend allows developers to
 
 While providers, routes, and tests, can live in the root backend project, consider putting data models and data access into their own dedicated package(s). Ideally, these layers should be able to exist independently from the rest of the app.
 
-```txt
-my_app/
-  |- api/
-  |  |- lib/
-  |  |  |- src/
-  |  |  |  |- middleware/
-  |  |- packages/
-  |  |  |- models/
-  |  |  |  |- lib/
-  |  |  |  |  |- src/
-  |  |  |  |  |  |- endpoint_models/
-  |  |  |  |  |  |- shared_models/
-  |  |  |  |- test/
-  |  |  |  |  |- src/
-  |  |  |  |  |  |- endpoint_models/
-  |  |  |  |  |  |- shared_models/
-  |  |  |- data_source/
-  |  |  |  |- lib/
-  |  |  |  |  |- src/
-  |  |  |  |- test/
-  |  |  |  |  |- src/
-  |  |- routes/
-  |  |  |- api/
-  |  |  |  |- v1/
-  |  |  |  |  |- todos/
-  |  |  |- test/
-  |  |  |  |- src/
-  |  |  |  |  |- middleware/
-  |  |  |  |- routes/
-  |  |  |  |  |- api/
-  |  |  |  |  |  |- v1/
-  |  |  |  |  |  |  |- todos/
-```
+<FileTree>
+
+- api/
+  - lib/
+    - src/
+      - middleware/
+  - packages/
+    - models/
+      - lib/
+        - src/
+          - endpoint_models/
+          - shared_models/
+      - test/
+        - src/
+          - endpoint_models/
+          - shared_models/
+    - data_source/
+      - lib/
+        - src/
+      - test/
+        - src/
+    - routes/
+      - api/
+        - v1/
+          - todos/
+      - test/
+        - src/
+          - middleware/
+        - routes/
+          - api/
+            - v1/
+              - todos/
+
+</FileTree>
 
 ### Models
 

diff --git a/...content/docs/architecture/barrel_files.md → ...ontent/docs/architecture/barrel_files.mdx b/...content/docs/architecture/barrel_files.md → ...ontent/docs/architecture/barrel_files.mdx
@@ -3,39 +3,45 @@ title: Barrel Files
 description: Best practices for exposing public facing files.
 ---
 
+import { FileTree } from "@astrojs/starlight/components";
+
 When building a package, a feature, or an API, we will create a folder structure with all the source code inside. If we stop here and don't export the files that will be required in other places of the app, we will force developers to have a long and messy import section. Furthermore, any refactor that affects file names in one feature will require changes in other places that could be avoided.
 
 For a package, the structure could look something like:
 
-```text
-my_package/
- |-lib/
- |   |- src/
- |   |    |- models/
- |   |    |    - model_1.dart
- |   |    |    - model_2.dart
- |   |    |- widgets/
- |   |    |    - widget_1.dart
- |   |    |    - widget_2.dart
- |- test/...
- |- pubspec.yaml
-```
+<FileTree>
+
+- my_package/
+  - lib/
+    - src/
+      - models/
+        - model_1.dart
+        - model_2.dart
+      - widgets/
+        - widget_1.dart
+        - widget_2.dart
+  - test/...
+  - pubspec.yaml
+
+</FileTree>
 
 And for a feature, it could look like:
 
-```text
-my_feature/
- |- bloc/
- |    - feature_bloc.dart
- |    - feature_event.dart
- |    - feature_state.dart
- |- view/
- |    - feature_page.dart
- |    - feature_view.dart
- |- widgets/
-      - widget_1.dart
-      - widget_2.dart
-```
+<FileTree>
+
+- my_feature/
+  - bloc/
+    - feature_bloc.dart
+    - feature_event.dart
+    - feature_state.dart
+  - view/
+    - feature_page.dart
+    - feature_view.dart
+  - widgets/
+    - widget_1.dart
+    - widget_2.dart
+
+</FileTree>
 
 In both cases, if we want to use both `widget_1.dart` and `widget_2.dart` in other parts of the app, we will have to import them separately like:
 
@@ -56,37 +62,41 @@ With these changes, let's update the folder structures for both scenarios.
 
 A package with barrel files should look like:
 
-```text
-my_package/
- |-lib/
- |   |- src/
- |   |    |- models/
- |   |    |    - model_1.dart
- |   |    |    - model_2.dart
- |   |    |    - models.dart
- |   |    |- widgets/
- |   |    |    - widget_1.dart
- |   |    |    - widget_2.dart
- |   |    |    - widgets.dart
- |   |- my_package.dart
- |- test/...
- |- pubspec.yaml
-```
+<FileTree>
+
+- my_package/
+  - lib/
+    - src/
+      - models/
+        - model_1.dart
+        - model_2.dart
+        - models.dart
+      - widgets/
+        - widget_1.dart
+        - widget_2.dart
+        - widgets.dart
+    - my_package.dart
+  - test/...
+  - pubspec.yaml
+
+</FileTree>
 
 And for a feature, it should look like:
 
-```text
-my_feature/
- |- bloc/
- |    - feature_bloc.dart
- |    - feature_event.dart
- |    - feature_state.dart
- |- view/
- |    - feature_page.dart
- |    - feature_view.dart
- |    - view.dart
- |- my_feature.dart
-```
+<FileTree>
+
+- my_feature/
+  - bloc/
+    - feature_bloc.dart
+    - feature_event.dart
+    - feature_state.dart
+  - view/
+    - feature_page.dart
+    - feature_view.dart
+    - view.dart
+  - my_feature.dart
+
+</FileTree>
 
 Finally let's see what these files contain. Continuing with the package example, we have three barrel files: `models.dart`, `widgets.dart` and `my_package.dart`.
 
@@ -119,12 +129,14 @@ In this example, we are exporting all files from the folder, but this is not alw
 
 By convention, blocs are typically broken into separate files consisting of the events, states, and the bloc itself:
 
-```text
-bloc/
+<FileTree>
+
+- bloc/
   - feature_bloc.dart
   - feature_event.dart
   - feature_state.dart
-```
+
+</FileTree>
 
 In this case, we don't add an extra barrel file since the `feature_bloc.dart` file is working as such, thanks to the `part of` directives. You can read more about it in the [bloc documentation][bloc_documentation].