Contributing Guide

Thank you for contributing to CommitToMemory! This guide covers everything you need to write and submit high-quality content.

Prerequisites

• Node.js >= 20.0
• A GitHub account
• Basic familiarity with Markdown

Quick Start

# 1. Fork and clone the repository
git clone https://github.com/<your-username>/CommitToMemory.git
cd CommitToMemory

# 2. Install dependencies
npm install

# 3. Start the dev server
npm start

Visit http://localhost:3000 to preview your changes live.

Where to Add Content

Choose the correct directory based on the topic:

Directory	Category	Example Topics
docs/intro/	Introduction	Project info, guides
docs/cs/	Computer Science	Data structures, algorithms
docs/dotnet/	.NET Platform	C#, LINQ, EF Core, async/await
docs/dotnet/csharp/	C# Language	Sub-topics under C#
docs/architecture/	Architecture & Design	SOLID, design patterns, DDD
docs/database/	Database	SQL, PostgreSQL, MongoDB, Redis
docs/system-design/	System Design	Scalability, caching, message brokers
docs/devops/	DevOps & Tooling	Docker, Git
docs/testing/	Testing	xUnit, NUnit, mocking

mẹo

When in doubt, look at sidebars.ts to see where existing topics are organized.

Step-by-Step: Add a New Topic

0. Prepare Your Data Sources

Before writing, gather and review your reference materials. Choosing reliable, authoritative sources is critical — the quality of your content depends directly on the quality of your sources.

Recommended source types:

Source Type	Examples	Reliability
Official documentation	Microsoft Learn, MDN, PostgreSQL docs	Highest
Foundational books	CLR via C#, Designing Data-Intensive Applications	High
Authoritative blogs	Martin Fowler, Microsoft Engineering, Stack Overflow Blog	High
RFCs & specifications	HTTP RFCs, language specifications	High
Community content	Medium articles, dev.to, Reddit	Medium — verify claims

Evaluate your sources

• Prefer primary sources (official docs, specs) over secondary summaries.
• Cross-reference claims from community content with official documentation.
• Check the publication date — outdated sources may describe deprecated APIs or patterns.
• Include all sources you used in the References section of your topic.

Avoid unreliable sources

• Unattributed blog posts or AI-generated content without verification.
• Stack Overflow answers without upvotes or accepted status.
• Documentation for a different version than what the topic covers.

1. Create the Markdown file

Create a .md file in the appropriate docs/ subdirectory.

2. Add frontmatter

Every file must start with this frontmatter block:

---
slug: /category/topic-name
title: Full Display Title
sidebar_label: Short Name
description: A concise SEO description (under 160 characters)
---

Rules:

• slug must be unique across the entire site and use kebab-case.
• sidebar_label should be short (ideally under 20 characters) so the sidebar stays readable.
• description should summarize the topic in one sentence.

3. Write content using the standard template

Use this structure so all topics stay consistent:

---
slug: /category/topic-name
title: Topic Title
sidebar_label: Short Name
description: Short SEO description
---

# Topic Title

## Definition

Brief explanation of what this topic is and why it matters.

## Core Concepts

### Concept 1
Explanation with code examples where applicable.

### Concept 2
Explanation with code examples where applicable.

## Code Examples

```csharp
// Practical, runnable code examples
```

## When to Use

Guidance on when this concept/tool/approach is appropriate.

## Common Pitfalls

Mistakes developers frequently make and how to avoid them.

## Key Takeaways

- Summary point 1
- Summary point 2
- Summary point 3

## Interview Questions

**Q: Sample interview question?**
A concise, correct answer.

**Q: Another question?**
Another concise answer.

## References

- [Reference Title](https://example.com)

Section order matters

Keep sections in the order shown above. Not every section is required for every topic, but the order should be consistent.

4. Register in the sidebar

Open sidebars.ts and add the file path (relative to docs/, without extension) to the correct category's items array:

// Example: adding a new topic under Architecture
items: [
  'architecture/solid-principles',
  'architecture/design-patterns',
  'architecture/your-new-topic',  // <-- add here
],

5. Preview and verify

# If the dev server is already running, it hot-reloads automatically.
# Otherwise:
npm start

Check that:

• The new page appears in the sidebar
• The frontmatter renders correctly (title, description)
• All code blocks highlight properly
• Mermaid diagrams render (if any)
• Links and references work

6. Commit and submit

git add docs/category/your-topic.md sidebars.ts
git commit -m "docs: add topic name to category"
git push

Then open a Pull Request on GitHub.

Writing Guidelines

Code Examples

• Use runnable code — avoid pseudocode or snippets that won't compile.
• Use the correct language tag in fences: ```csharp, ```sql, ```bash.
• Keep examples focused — one concept per code block.
• Add inline comments to explain non-obvious parts.

Supported syntax highlighting languages: bash, csharp, javascript, typescript, python, java, go, rust, sql.

Diagrams

Use Mermaid for diagrams:

Supported diagram types: flowchart, sequenceDiagram, classDiagram, graph.

Callouts

Use Docusaurus admonitions to highlight important information:

:::tip[Pro Tip]
Something useful that goes beyond the basics.
:::

:::warning[Watch Out]
A common mistake or edge case to be aware of.
:::

:::danger[Critical]
Something that can cause data loss, security issues, or production failures.
:::

Interview Questions

• Aim for 3-5 questions per topic.
• Cover a mix of conceptual and practical questions.
• Keep answers concise but complete.
• Mark advanced questions with (Advanced) in the question text.

Content Quality Checklist

Before submitting, verify your content:

• Frontmatter is complete (slug, title, sidebar_label, description)
• Slug is unique and uses kebab-case
• File is registered in sidebars.ts
• Code examples are correct and runnable
• Code fences use the correct language tag
• Mermaid diagrams render correctly (if any)
• Content follows the standard section template
• Interview questions have accurate answers
• No spelling or grammar errors
• All links and references are valid

File Naming Convention

Use kebab-case for file names:

solid-principles.md     # correct
SolidPrinciples.md      # wrong
solid_principles.md     # wrong

Commit Message Format

Use conventional commit prefixes:

docs: add dependency injection to .NET Platform
docs: update SOLID principles with new examples
fix: correct async/await code example
feat: add new category "Cloud & Infrastructure"

Need Help?

• Open an issue on GitHub for questions or proposals.
• Look at existing topics in the repository for reference on style and depth.
• Check Docusaurus Docs for platform-specific questions.