Hey there! Welcome to Sutra, a blog platform I built to jot down my everyday notes to build a second brain. (Inspired by the book, building a second brain). This project started as a simple portfolio piece but quickly evolved into something I'm really proud of. I wanted to create something that wasn't just functional but also beautiful and technically impressive.
What you're looking at is a full-featured blog built with Next.js, React, and TypeScript. I've poured countless hours into making it both visually appealing and technically sound. Let me walk you through what makes it special.
I spent a ton of time making sure the site looks awesome whether you're on a phone, tablet, or desktop. The animations (powered by Framer Motion) add that extra touch that makes scrolling through content feel satisfying. I'm particularly proud of how the mobile menu transitions!
As a developer, I love Markdown, so I made sure the platform handles it beautifully. Code snippets get syntax highlighting automatically (thanks to Highlight.js), and I built custom components that can be embedded right in the content. This README itself is written in Markdown!
One of the coolest features is built-in support for Mermaid diagrams! You can embed diagrams directly in your blog posts or documentation using Markdown code blocks with the 'mermaid' language specifier. The diagrams are rendered beautifully and are fully responsive. Check out the architecture diagram below in the "How It All Fits Together" section - it's actually a Mermaid diagram rendered in real-time!
The search feature was one of the most challenging parts to get right. I implemented a client-side search that updates results as you type, and it even highlights where your search terms appear in the results. Try searching for something when you run the site - it's surprisingly snappy!
I built every component from scratch (no UI libraries here!). The animated gradient backgrounds adjust based on the time of day, the toast notification system stacks messages elegantly, and the project cards flip to reveal details. The tech badges were a last-minute addition that I think really make the projects section pop.
Performance was a huge focus. I leveraged Next.js's static site generation for blog posts, which means they load almost instantly. Images are automatically optimized using Sharp, and I integrated Vercel Analytics to keep an eye on real-world performance metrics. I'm proud to say the site achieves a perfect 100% Lighthouse score across all categories (Performance (down to 80 after refactoring, working on fixing this atm), Accessibility, Best Practices, and SEO)!
I'll be honest - I almost skipped proper testing. But I'm glad I didn't! The Jest and React Testing Library setup catches bugs before they make it to production. The integration tests for the blog functionality were particularly tricky to get right because of all the async data fetching, but they've saved me from shipping broken features multiple times.
Here's a visual of how all the pieces connect:
graph TD subgraph Client A[User Browser] --> B[Next.js Frontend] end subgraph "Next.js Server" B <--> C[Page Router] C --> D[Static Pages] C --> E[Server Components] C --> F[Client Components] E --> G[Data Fetching Layer] F --> H[UI Components] subgraph "Content Processing" G --> I[Markdown Processing] I --> J[Syntax Highlighting] I --> K[MDX Components] end end subgraph "Data Sources" G <--> L[File System] G <--> M[Notion API] end subgraph "Testing Infrastructure" N[Jest] --> B O[Storybook] --> H P[Integration Tests] --> B end subgraph "Deployment" B --> Q[Vercel] Q --> R[CDN] R --> A end
This diagram helped me visualize the data flow when I was refactoring the content processing pipeline. The trickiest part was getting the Notion API integration working smoothly with the static generation.
sutra/
βββ src/
β βββ app/ # Next.js App Router
β β βββ blog/ # Blog pages
β β βββ projects/ # Projects showcase
β β βββ about/ # About page
β β βββ books/ # Books recommendations
β βββ components/ # Reusable UI components
β β βββ ui/ # Base UI components
β β βββ home/ # Home page components
β β βββ Navbar/ # Navigation components
β βββ context/ # React context providers
β βββ data/ # Data sources and models
β βββ lib/ # Utility libraries
β βββ utils/ # Helper functions
β βββ stories/ # Storybook stories
β βββ __tests__/ # Test files
β βββ integration/ # Integration tests
βββ public/ # Static assets
βββ .storybook/ # Storybook configuration
βββ ... # Configuration files
I spent a lot of time thinking about this structure. The separation between UI components and page-specific components has saved me from a lot of headaches as the project grew.
tsx
git clone https://github.com/brgv-code/sutra.git cd sutra
tsx
yarn install # or npm install
tsx
yarn dev # or npm run dev
Hot tip: The first load might be a bit slow because of all the optimizations happening behind the scenes, but subsequent refreshes should be lightning fast.
I'm constantly working to make Sutra even better. Here's what I'm planning to add in the coming months:
I'm tackling these roughly in order, but priorities might shift based on feedback. If you're particularly interested in seeing any of these features sooner, let me know!
I'm pretty proud of the test coverage. Here's how to run them:
tsx
yarn test # or npm test
If you're making changes, the watch mode is super helpful:
tsx
yarn test:watch # or npm run test:watch
Want to see the coverage report? This will generate a nice HTML report:
tsx
yarn test:coverage # or npm run test:coverage
I'm in the process of implementing Storybook for component development:
tsx
yarn storybook # or npm run storybook
Note: Storybook integration is still a work in progress. Not all components have stories yet, and the configuration is being refined. I'm gradually adding stories for each component, starting with the core UI elements.
Once fully implemented, this will provide a component explorer where you can see and interact with all UI components in isolation - making it much easier to develop and test components without navigating through the entire app.
If you want to use the Notion integration, you'll need to set up a few environment variables:
NOTION_API_KEY=your_notion_api_key
NOTION_DATABASE_ID=your_notion_database_id
I've included a sample .env.example
file that you can copy to .env.local
and
fill in with your own values.
I've set up both Docker and Devbox to make development environment consistent and easy to get started with.
The project includes Docker configuration for both development and production:
tsx
# For development with hot-reloading docker-compose up # For production build docker build -t sutra-blog . docker run -p 3000:3000 sutra-blog
Note: If you're using Docker for development, any changes you make to the code will be reflected immediately thanks to the volume mounting in docker-compose.yml.
I'm using Devbox to ensure consistent development environments:
tsx
# Install Devbox if you don't have it curl -fsSL https://get.jetpack.io/devbox | bash # Start the Devbox shell devbox shell # This will automatically install Node.js 20.10.0, Yarn, and EdgeDB # and run yarn install thanks to the init_hook
The project is configured to use EdgeDB for data storage:
tsx
# Initialize EdgeDB (run this once) edgedb project init # Apply migrations edgedb migration apply
I'm still in the process of fully implementing the EdgeDB backend, so some features might still use file-based storage. Check the roadmap for the full database implementation plan!
This project is under the MIT License - see the LICENSE file for details. Feel free to use any parts of it for your own projects!
This project wouldn't have been possible without:
And a special thanks to the open source community for all the amazing packages that made this project possible. I've learned so much by reading through your code!
If you have any questions or just want to chat about the project, feel free to reach out! I'm always happy to talk about web development.