Building Documentation and Portfolio Website
This project focuses on building a documentation and portfolio website using Astro and Tailwind CSS. All necessary steps from scratch will be covered in this project. The website will serve as a platform to showcase your work, share your knowledge, and connect with potential clients or employers.
1Project Roadmap: Step-by-Step Navigation
Why Build a Documentation and Portfolio Website?
In today’s digital age, having an online presence is crucial for professionals in various fields. A documentation and portfolio website serves as a platform to showcase your work, share your knowledge, and connect with potential clients or employers. It allows you to demonstrate your skills, highlight your projects, and establish yourself as an authority in your industry. By building a documentation and portfolio website, you can:
- Showcase Your Work: A well-designed website provides a visually appealing way to display your projects, achievements, and skills. It allows you to present your work in a professional manner, making it easier for visitors to understand your capabilities.
- Share Your Knowledge: A documentation website allows you to share your expertise and insights with others. You can create tutorials, write articles, and provide valuable resources that can help others learn and grow in their respective fields.
- Connect with Others: An online portfolio can help you connect with potential clients, employers, and collaborators. It serves as a central hub where people can learn more about you, your work, and how to contact you.
- Establish Your Personal Brand: A well-crafted website can help you establish your personal brand and differentiate yourself from others in your industry. It allows you to communicate your unique value proposition and create a memorable impression on visitors.
- Enhance Your Career Opportunities: A strong online presence can open up new career opportunities. Employers and clients often search for candidates online, and having a professional website can increase your chances of being noticed and hired.
- Demonstrate Your Skills: Building a website allows you to demonstrate your technical skills, such as web development, design, and content creation. It provides a tangible example of your abilities that can impress potential employers or clients.
- Stay Updated: A documentation website can serve as a platform to share updates about your projects, industry trends, and personal achievements. It allows you to keep your audience informed and engaged with your work.
Overall, building a documentation and portfolio website is a valuable investment in your professional growth and online presence. It can help you showcase your work, share your knowledge, connect with others, establish your personal brand, enhance your career opportunities, demonstrate your skills, and stay updated with industry trends.
Why not Notion, Medium or other platforms?
Using ready made platforms like Notion, Medium, or others has following advantages and disadvantages:
Advantages
- It is easy to use and requires no coding knowledge.
- It provides a user-friendly interface for creating and organizing content.
- It offers built-in templates and features for creating documentation and portfolios.
- It allows for easy collaboration and sharing with others.
- It provides hosting and maintenance, eliminating the need for technical setup.
- Managing content is easier as it provides a centralized platform for all your documentation and portfolio needs.
- Manual updates and maintenance are not required as the platform takes care of it.
Disadvantages
- Customization is limited, and you may not be able to achieve the exact look and feel you want for your website.
- You may have limited control over the functionality and features of your website, as you are restricted to what the platform offers.
- You may have to pay for premium features or subscriptions to access certain functionalities or remove ads.
- You may have limited options for integrating third-party tools or services, which can restrict the capabilities of your website.
- You can never have unlimited customization and control over your website, as you are dependent on the platform's updates and changes.
- You depend on the platform's stability and security, and if the platform experiences downtime or security breaches, it can affect your website and its visitors.
- Theme and design options are very limited compared to building your own website, which can make it difficult to create a unique and personalized online presence.
- Your platform will look like copy-paste of other websites using the same platform, which can make it difficult to stand out and differentiate yourself from others in your industry.
So, the main problem of using other ready made platforms is their limits and the restricted control over the design, functionality, and customization of your website. Building your own documentation and portfolio website allows you to have complete control over the look, feel, and features of your site, enabling you to create a unique and personalized online presence that truly represents you and your work. This will also give you the opportunity to learn and demonstrate your web development skills, which can be valuable for your career growth and opportunities and hence increase your confidence in your technical abilities.
Which Technologies to Use?
For building a documentation and portfolio website, there are several technologies you can consider. Here are some popular options:
- Astro: Astro is a modern static site generator that allows you to build fast and optimized websites. It supports multiple frameworks and provides a great developer experience. Astro is a good choice for building a documentation and portfolio website due to its performance and flexibility. There are also many templates available for Astro that can help you get started quickly. For example, Starlight is a popular Astro template that is designed for documentation and portfolio websites. It provides a clean and modern design, along with features like dark mode, responsive layout, and easy customization.
- Hugo: Hugo is another popular static site generator that is known for its speed and simplicity. It has a large community and a wide range of themes available, making it a good choice for building a documentation and portfolio website. It has also a good documentation and portfolio template called Docsy, Blowfish which are designed for technical documentation and project portfolios. It provides a clean and professional design, along with features like search functionality, responsive layout, and easy customization.
- Jekyll: Jekyll is a static site generator that is built on Ruby. It is widely used for building blogs and documentation websites. Jekyll has a large community and a wide range of themes available, making it a good choice for building a documentation and portfolio website. It has also a good documentation and portfolio template called Just the Docs, Minimal Mistakes which are designed for technical documentation and project portfolios. It provides a clean and professional design, along with features like search functionality, responsive layout, and easy customization.
- Gatsby: Gatsby is a React-based static site generator that allows you to build fast and dynamic websites. It has a large ecosystem of plugins and themes, making it a good choice for building a documentation and portfolio website. Gatsby has a good documentation and portfolio template called Gatsby Starter Portfolio, which is designed for showcasing projects and skills. It provides a modern and visually appealing design, along with features like responsive layout, easy customization, and integration with various data sources.
- MkDocs: MkDocs is a static site generator that is specifically designed for building documentation websites. It is written in Python and has a simple and intuitive configuration. MkDocs has a good documentation template called Material for MkDocs, which is designed for technical documentation. It provides a clean and modern design, along with features like search functionality, responsive layout, and easy customization.
- Docusaurus: Docusaurus is well suited for building documentation websites, especially for open-source projects. It is built on React and provides a simple and intuitive way to create and maintain documentation. Docusaurus has a good documentation template called Classic, which is designed for technical documentation. It provides a clean and modern design, along with features like search functionality, responsive layout, and easy customization.
There are more technologies available for building documentation and portfolio websites, and the choice ultimately depends on your specific needs, preferences, and technical skills. It is important to consider factors such as ease of use, customization options, performance, and community support when selecting the right technology for your project.
I will not dive deeper into the comparison of these technologies in this project, but I will be clearly list all advantages and disadvantages of using Astro together with Tailwind CSS for building a documentation and portfolio website in the next section.
Advantages of using Astro and Tailwind CSS
- Zero-JS "Islands" Architecture: Astro ships pure, lightning-fast HTML by default. It only loads JavaScript for the specific interactive components you choose, eliminating the heavy bundle bloat seen in React-based generators like Gatsby or Docusaurus.
- Unrestricted Customization: Instead of fighting against the constraints of rigid, pre-built themes that often prove insufficient for custom needs, Tailwind allows you to build exactly what you want directly in your markup.
- "Bring Your Own Framework" Flexibility: You are not locked into a single ecosystem. You can seamlessly drop React, Vue, Svelte, or SolidJS components into the same Astro project.
- First-Class Tailwind Support: Astro integrates Tailwind natively. It automatically handles the build process and CSS purging without the messy PostCSS pipelines required by Jekyll or older tools. Hugo requires manually setting up Node dependencies, PostCSS, and configuring complex asset pipelines just to get Tailwind working properly.
- Advanced MDX Capabilities: Moving beyond traditional documentation setups, Astro treats Markdown and MDX as first-class citizens. You can easily embed dynamic, interactive components directly into your Markdown files without relying on clunky shortcodes. Hugo forces you to use its proprietary "shortcode" syntax, which is less flexible and harder to debug.
- Modern Developer Experience: Powered by Vite, Astro offers near-instant Hot Module Replacement (HMR). You see your Tailwind class changes and component updates immediately, making the development loop significantly faster than older Go or Ruby-based generators.
- Total Customization Control: Instead of feeling boxed in by rigid templates or struggling to override deep styling in themes like Hugo Blowfish, Astro and Tailwind let you build the exact UI you envision without fighting an underlying theme architecture.
- Intuitive Component System: Astro uses a modern, HTML-like component structure that is very familiar to web developers. Hugo relies on Go templating, which can have a steep learning curve and become messy when handling complex logic.
- Painless Interactivity: If you ever need to add a dynamic React, Vue, or Svelte component (like a complex data visualization), Astro handles it natively through its "Islands" architecture. With Hugo, you have to manually wire up vanilla JavaScript or write custom build scripts.
- Full Access to NPM: Astro lives natively in the modern web ecosystem, meaning you can easily install and use any package from NPM. Hugo is a standalone Go binary, making it much harder to integrate standard JavaScript libraries.
- Built-in Image Optimization: Astro has native support for image optimization, allowing you to easily serve responsive images without additional configuration. Hugo requires manual setup and third-party tools for similar functionality.
- Perfect Code Syntax Highlighting - Shiki: Astro uses Shiki for code syntax highlighting, which is more flexible and easier to customize than Hugo's built-in Chroma highlighter. Shiki is the engine that is used by Visual Studio Code and GitHub to provide seamless integration.
Disadvantages of using Astro and Tailwind CSS
- Slower Build Times for Massive Sites (vs. Hugo) If you are building a massive enterprise documentation site with tens of thousands of pages, Hugo (written in Go) will compile it in seconds, whereas Astro will take noticeably longer. However, it is still faster than most of the other website generators.
- A Steeper Learning Curve for Non-JS Developers (vs. MkDocs & Jekyll) Astro and Tailwind CSS require a certain level of JavaScript knowledge, which might be a barrier for developers who are more comfortable with static site generators like MkDocs or Jekyll.
- The "Blank Slate" Overhead (vs. Pre-configured Themes) Starting from scratch with Astro and Tailwind CSS means more initial setup time compared to using pre-configured themes in tools like MkDocs or Jekyll. However, this also provides greater flexibility and control over the final product.
- Overkill for Simple Static Content If your documentation or portfolio needs are very basic and do not require custom design or interactivity, using Astro and Tailwind CSS might be overkill compared to simpler platforms like Mkdocs or Jekyll.
- Less Mature Ecosystem (vs. Hugo & Jekyll) While Astro is rapidly growing, it is still a newer tool compared to established generators like Hugo and Jekyll, which have larger communities and more plugins/themes available. However, you can apply any theme to your website using Tailwind CSS even though it requires manual effort.
- Requires Node.js Environment Astro requires a Node.js environment for development and building, which might not be ideal for all users, especially those who prefer a more lightweight setup without the need for a JavaScript runtime.
Overall, while there are some disadvantages to using Astro and Tailwind CSS, the advantages in terms of customization, performance, and developer experience make it a compelling choice for building a documentation and portfolio website. The flexibility and control it offers can help you create a unique and personalized online presence that truly represents you and your work.
Astro Project Folder Structure
When building a documentation and portfolio website using Astro and Tailwind CSS, it is important to organize your project files in a clear and logical manner. When you create a new Astro project, it will generate a default folder structure for you. However, it is better to understand it not roughly. Here is a typical folder structure for an Astro project:
We will dive deeper into the folder structure and the purpose of each file in the next sections of this project. For now, it is important to understand that this structure is designed to keep your project organized and maintainable as it grows in complexity. Each folder serves a specific purpose, and following this structure will help you manage your code and content effectively as you build your documentation and portfolio website.
Whole Project Roadmap
The project will be divided within the following steps:
Astro & Tailwind Setup
Initialize the project using the Astro CLI and install Tailwind CSS integration to build our utility-first styling foundation.
Folder Structure & Config
Organize the directory with components, layouts, and pages. Configure src/content.config.ts to define our Zod-powered schemas for data science and articles.
Main & Article Layouts
Develop MainLayout.astro for global SEO/HTML and ArticleLayout.astro with our custom sidebar, TOC, and interactive code copy scripts.
Navbar & Project Roadmap
Implement the top navigation menu and the ProjectNavigation.astro component to handle step-by-step guidance within project series.
Markdown & MDX Collections
Populate the src/content/ directories with your data science projects, thesis chapters, and technical articles using our custom shortcodes.
Dynamic Slug Generation
Create [...slug].astro files in the pages directory to automatically generate clean URLs and handle data injection for all content collections.
Shortcodes & Math Rendering
Finalize the CSS for file-trees, comparison boxes, and KaTeX math blocks to ensure a premium reading experience.
Repository Initialization
Initialize a local Git repository, create a .gitignore, and push the source code to a private or public GitHub repository.
GitHub Actions Setup
Configure a GitHub Action (deploy.yml) to automatically build the project and deploy it to GitHub Pages or a cloud provider on every push.
Deployment & Live Preview
Verify the production build, check the SSL certificate, and officially launch your portfolio to the world at your custom domain.
After completing these steps, you will have a fully functional documentation and portfolio website built with Astro and Tailwind CSS.
Attention
Please note that the steps are not strictly linear, and you may find yourself iterating between them as you build and refine your website. The key is to focus on one aspect at a time while keeping the overall architecture and design in mind. By following this roadmap, you will be able to create a professional and personalized online presence that effectively showcases your work and expertise.
Conclusion
Building a documentation and portfolio website using Astro and Tailwind CSS is a rewarding project that allows you to showcase your work, share your knowledge, and establish your online presence. By following the steps outlined in this roadmap, you can create a unique and personalized website that truly represents you and your work. Remember to focus on one aspect at a time, iterate as needed, and enjoy the process of building your own online space to share with the world.