MarsBased · mb-maxime-ancelin · Mar 5, 2026
diff --git a/guides/development/coding-guidelines.md b/guides/development/coding-guidelines.md
@@ -4,71 +4,71 @@ Writing code can be as personal as hand-writing but we like to keep everyone wit
 
 Focus on code readability. Code should tell a story. Code should be easy to understand and reason about by anyone.
 
-* **1.** [Do's and Don'ts](#DosandDonts)
-	* **1.1** [Do's](#Dos)
-		* **1.1.1** [Keep code simple](#KeepCodeSimple)
-		* **1.1.2** [Naming is key](#Naming)
-		* **1.1.3** [Remove unused code](#UnusedCode)
-		* **1.1.4** [Write meaningful code comments](#CodeComments)
-		* **1.1.5** [Keep it small](#KeepItSmall)
-	* **1.2** [Don'ts](#Donts)
-		* **1.2.1** [Refactor ahead of time](#RefactorAheadOfTime)
-		* **1.2.2** [Premature optimization](#PrematureOptimization)
-		* **1.2.3** [Unnecessary dependencies](#UnnecessaryDependencies)
-		* **1.2.4** [Don't comment code to remove it, just delete it](#CommentCodeToRemove)
-		* **1.2.5** [Refactor and add features](#RefactorAndAddFeatures)
-		* **1.2.6** [Don't make typos](#DontMakeTypos)
-		* **1.2.7** [Avoid comments with TODOs](#AvoidTODOs)
-
-## 1. <a name="DosandDonts"></a>Do's and Don'ts
-
-### 1.1 <a name='Dos'></a>Do's
-
-#### 1.1.1 <a name='KeepCodeSimple'></a>Keep Code Simple
+* **1.** [Do's and Don'ts](#1-dos-and-donts)
+	* **1.1** [Do's](#11-dos)
+		* **1.1.1** [Keep code simple](#111-keep-code-simple)
+		* **1.1.2** [Naming is key](#112-naming-is-key)
+		* **1.1.3** [Remove unused code](#113-remove-unused-code)
+		* **1.1.4** [Write meaningful code comments](#114-write-meaningful-code-comments)
+		* **1.1.5** [Keep it small](#115-keep-it-small)
+	* **1.2** [Don'ts](#12-donts)
+		* **1.2.1** [Refactor ahead of time](#121-dont-refactor-ahead-of-time)
+		* **1.2.2** [Premature optimization](#122-premature-optimization)
+		* **1.2.3** [Unnecessary dependencies](#123-unnecessary-dependencies)
+		* **1.2.4** [Don't comment code to remove it, just delete it](#124-dont-comment-code-to-remove-it-just-delete-it)
+		* **1.2.5** [Refactor and add features](#125-refactor-and-add-features)
+		* **1.2.6** [Don't make typos](#126-dont-make-typos)
+		* **1.2.7** [Avoid comments with TODOs](#127-avoid-comments-with-todos)
+
+## 1. Do's and Don'ts
+
+### 1.1 Do's
+
+#### 1.1.1 Keep Code Simple
 Code should be simple! Easy to understand. Variables and methods with good naming. Methods short, classes small. Code should be properly organized for this purpose. Sometimes we can think of some design patterns that could be applied or some (complex) abstractions but these can lead to over-engineering. Your code as a purpose, focus on that. Let the patterns, the abstractions, the complexity come to you instead of driving you.
 
 [Keep it simple, stupid](https://en.wikipedia.org/wiki/KISS_principle).
 
-#### 1.1.2 <a name='Naming'></a>Naming is key
+#### 1.1.2 Naming is key
 Spend some time looking for good classes, methods and variables names. Make use of long and descriptive names for both functions/methods and variables. Never use 1 char variables! Remember you are writing code for others and for you, make it the best. Push to give the readers a good time.
 
 Naming is key!
 
-#### 1.1.3 <a name='UnusedCode'></a>Remove unused code
+#### 1.1.3 Remove unused code
 When we stop using a feature or part of it we should remove that code and any other unused code as a consequence. Remember, we don't want "dead" code around. It will give you a hard time later when you need to comprehend it again.
 
-#### 1.1.4 <a name='CodeComments'></a>Write meaningful code comments
+#### 1.1.4 Write meaningful code comments
 Don't comment the WHAT about a piece of code, only the WHY, and if necessary. Comments should exist if you believe that the solution you've chosen might need extra context to be understood. Always focus on the WHY instead of the WHAT as this last one is already there, is our code.
 
-#### 1.1.5 <a name='KeepItSmall'></a>Keep it small
+#### 1.1.5 Keep it small
 Less code the better, less code changes the better. As we like to build one thing at a time we should also built it as simple and focused as possible. Less code makes it better to understand, less code changes make it much more accessible for you and our colleagues as reviewers.
 
-### 1.2 <a name='Donts'></a>Don'ts
+### 1.2 Don'ts
 
-#### 1.2.1 <a name='RefactorAheadOfTime'></a>Don't refactor ahead of time
+#### 1.2.1 Don't refactor ahead of time
 Wait until something is painful to change or understand. Remember that we should keep it small and simple. Refactor without a purpose can lead to complexity, unnecessary abstractions and miscommunication about what you are trying to achieve.
 
-#### 1.2.2 <a name='PrematureOptimization'></a>Premature optimization
+#### 1.2.2 Premature optimization
 In general don't do premature optimization, but always keep in mind that there are some basic techniques that can have big impact. Avoid N+1 queries (take advantage of the logs during development for this). Filter using SQL as long as possible (but keep a balance to avoid over-complicating the code). There are problems that can be avoided at first but don't go to deep blindly if there isn't any reason to.
 
-#### 1.2.3 <a name='UnnecessaryDependencies'></a>Unnecessary dependencies
+#### 1.2.3 Unnecessary dependencies
 Before adding a 3rd party library or a dependency think carefully if it's really necessary and the compromises you are making. We don't want to re-invent the wheel but sometimes it could be better to build what we need instead of depend on some library that do that and much more.
 
 When adding a new library to an application, make sure:
 * It's well maintained (check when the last commit was made and the number of open issues).
 * It's not unnecessarily big and does not introduce a lot of extra dependencies under the hood.
 * The license fits within the policy used in the application. Some projects only allow to have libraries using the MIT license, for example. Before adding a library with a more restrictive license, check with the team.
 
-#### 1.2.4 <a name='CommentCodeToRemove'></a>Don't comment code to remove it, just delete it
+#### 1.2.4 Don't comment code to remove it, just delete it
 We have git for god's sake. We can always check a previous commit to find the deleted code.
 
-#### 1.2.5 <a name='RefactorAndAddFeatures'></a>Refactor and add features
+#### 1.2.5 Refactor and add features
 Don't build new features and refactor at the same time unless that feature demands it. Focus on your current code and use code refactoring as a tool to achieve our goal. Refactor an unrelated part of the code that has nothing to do with that feature will not bring any value to you, to the reviewer and your codebase.
 
-#### 1.2.6 <a name='DontMakeTypos'></a>Don't Make Typos
+#### 1.2.6 Don't Make Typos
 Be careful with your typing. Writing classes/methods/variable names, code comments, literal string/page copies and documentation should be free of typos.
 
 Let your editor help you by installing a spell checker. Check [this plugin](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) if you are using Visual Studio Code. Remember, checking typos is part of code reviews.
 
-#### 1.2.7 <a name='AvoidTODOs'></a>Avoid comments with TODOs
+#### 1.2.7 Avoid comments with TODOs
 If there is something that you think it should be done create an issue for it. Maybe it will be done right after, or maybe some weeks after. Let that decision be where it belongs, in your project management tool. Your code is not the place to leave tasks descriptions or memos.
diff --git a/guides/development/git-guidelines.md b/guides/development/git-guidelines.md
@@ -2,25 +2,25 @@
 
 This is a guide covering how we expect to work with Git at MarsBased. Most of this guide is GitHub oriented but might be adapted to other Git tools like GitLab or Bitbucket.
 
-- **1.** [Commit Message Guidelines](#commitmessageguidelines)
-- **1.1** [Message Format](#messageformat)
-- **1.1.1** [Message Header Type](#headertype)
-- **1.1.2** [Message Header Scope](#headerscope)
-- **1.1.3** [Message Samples](#commitmessagesamples)
-- **2.** [Git Branches Naming](#gitbranchesnaming)
-- **3.** [Git Workflow](#gitworkflow)
-- **4.** [Dangerous behaviours](#dangerousbehaviours)
+- **1.** [Commit Message Guidelines](#commit-message-guidelines)
+- **1.1** [Message Format](#commit-message-format)
+- **1.1.1** [Message Header Type](#type)
+- **1.1.2** [Message Header Scope](#scope)
+- **1.1.3** [Message Samples](#commit-message-samples)
+- **2.** [Git Branches Naming](#git-branches-naming)
+- **3.** [Git Workflow](#git-workflow)
+- **4.** [Dangerous behaviours](#dangerous-behaviours)
 - **5.** [Credits](#credits)
 
 At MarsBased we work with a large variety of clients. Some clients may follow their own guidelines. You can always suggest improvements over their guidelines but there will be cases where it will not be possible to use ours.
 
-## <a name="commitmessageguidelines"></a>Commit Message Guidelines
+## Commit Message Guidelines
 
 We have very precise rules on how git commit messages should be formatted. This leads to more readable messages that are easy to follow when reviewing the project history.
 
 We use **Linear** as our tracking tool. Whenever possible, commit messages should reference the related Linear issue.
 
-### <a name="messageformat"></a>Commit Message Format
+### Commit Message Format
 
 Each commit message consists of a header and an optional description.
 
@@ -45,7 +45,7 @@ The maximum length of the header must be 72 characters. Any other line of the co
 
 The language used in commit messages is English. If the client needs access to the commit history for documentation purposes and does not understand English, other languages may be used instead.
 
-### <a name="headertype"></a>Type
+### Type
 
 Choose the type that best fits the task:
 
@@ -56,7 +56,7 @@ Choose the type that best fits the task:
 - **docs**: Documentation-only changes.
 - **test**: Adding or fixing tests.
 
-### <a name="headerscope"></a>Scope
+### Scope
 
 The scope describes the specific module or part of the application affected by the change. It is optional.
 
@@ -66,7 +66,7 @@ Examples:
 - **users**: User management.
 - **payment**: Payment gateway.
 
-### <a name="commitmessagesamples"></a>Commit Message Samples
+### Commit Message Samples
 
 With a Linear issue:
 
@@ -88,7 +88,7 @@ Without a Linear issue (`feat` is not allowed):
 fix: update Docker base image to v2.6
 ```
 
-## <a name="gitbranchesnaming"></a>Git Branches Naming
+## Git Branches Naming
 
 Any branch created for a project must follow these rules.
 
@@ -116,7 +116,7 @@ Examples:
 
 For client projects, adapt the naming to their requirements if needed.
 
-## <a name="gitworkflow"></a>Git Workflow
+## Git Workflow
 
 We use a simplified version of Gitflow.
 
@@ -147,11 +147,11 @@ For small projects or small teams, we usually keep things simpler by working wit
 
 Even in this simplified setup, we still work with short-lived branches per feature or fix, open Pull Requests, and perform code reviews before merging into `main`.
 
-## <a name="dangerousbehaviours"></a>Dangerous behaviours
+## Dangerous behaviours
 
 - Avoid using `git push -f` when working on a shared branch. Use `git push --force-with-lease` instead.
 
-## <a name="credits"></a>Credits
+## Credits
 
 This guide is heavily influenced by: