How I Built My Personal Website Using Just Markdown — No Coding Skills Needed!
Markdown is like a magical shortcut for formatting text. With just a few characters, you can create headers, lists, bold or italic text, and even add links and images. It’s perfect for writing blog posts, documentation, or even creating a personal website, like I did!
It’s super easy to learn and use. You don’t need any special software — just a plain text editor will do. Plus, it works almost everywhere, from GitHub to content management systems.
Introducing MkDocs
MkDocs is a powerful static site generator that’s designed with one main goal in mind: to make it incredibly easy for you to create beautiful, well-organized documentation. What makes MkDocs truly special is that it works entirely with Markdown.
The beauty of MkDocs lies in its simplicity. You don’t need to be a web developer to create a professional-looking site. The setup is straightforward: you install MkDocs, write your documentation in Markdown, and configure your site with a simple YAML file. This configuration file allows you to set the structure of your site, choose a theme, and tweak various settings without diving into complex code. Once you’re ready, a single command builds your entire site.
MkDocs is primarily designed to build documentation, but when I first saw the home image of an MkDocs-generated website, I was struck by how cool it looked. It immediately sparked an idea: why not use it for my personal resume website?
As a big fan of the Cloud Resume Challenge, I had already completed it and learned an incredible amount along the way. However, I spent a significant amount of time on the frontend part of the project. I wanted my website to look really cool without investing too much time again.
With MkDocs, I found the perfect solution. It allowed me to create a visually appealing and well-organized site using only Markdown. The simple configuration options and pre-built themes meant I could focus on showcasing my skills and experiences, while MkDocs took care of the presentation. The result was a sleek, professional resume website that stands out, all thanks to the power and simplicity of MkDocs.
How I Did It
First, we need to start with all the prerequisites listed here. This includes having Python and pip installed on your system, as well as installing MkDocs and the Material for MkDocs theme. Once you have these prerequisites in place, you’re ready to begin.
Next, create a new directory for your project and navigate into it. Then, run the command:
mkdocs new .This command initializes a new MkDocs project in your current directory. After running the command, you’ll notice two new files: mkdocs.yml and docs/index.md.
mkdocs.yml: This is the configuration file for your MkDocs project. Here, you can set various options such as the site name, theme, navigation structure, and additional settings like plugins and extensions. The mkdocs.yml file is where you define the structure and appearance of your website.
docs/index.md: This is the main Markdown file for your documentation (or in this case, your resume). The index.md file is the starting point for your content. You can use Markdown to format this file, adding sections, headers, lists, links, and images to build out your resume.
First, let’s modify the mkdocs.yml file. Open it in your favorite text editor and add somthing similar to the following code:
site_name: Carlos Cano Personal Website
site_url: https://yourdomain.com/
nav:
- Home: index.md
- Experience: experience.md
- Projects: projects.md
- Blog:
- Blog1: myblog1.md
- Blog2: myblog2.mdHere’s what each part of this configuration does:
- site_name: This sets the name of your website, which will appear in the navigation bar and browser title.
- site_url: This is the URL where your site will be hosted. Replace
https://yourdomain.com/with your actual domain name. - nav: This section defines the navigation structure of your site. Each entry corresponds to a Markdown file that will be rendered as a page on your site.
- Home: This links to
index.md, the main page of the website. - Experience: This links to
experience.md, where you can detail your professional experience. - Projects: This links to
projects.md, where you can showcase your projects. - Blog: This creates a dropdown menu in the navigation bar with links to
myblog1.mdandmyblog2.md, where you can write your blog posts.
Next, we’ll run the following command:
mkdocs serve This command starts a local development server, which allows you to preview your website in real-time as you make changes (No need to refresh).
In my case, the link to open the local development server is:
Simply click on the link or paste it into your browser’s address bar. You’ll be able to view your personal website and see your changes instantly.
And we will get something like this
Looks cool, right? But let’s modify the index.md file to make it even cooler.
Here’s an updated version of index.md to give your website a more polished and engaging look
# Welcome to Carlos Cano's Personal Website
## About Me
Hi, I'm Carlos Cano! I'm a passionate developer with a strong background in cloud technologies, frontend development, and more. Welcome to my personal website where you can learn more about my experience, projects, and thoughts on technology.
### Skills
- **Languages:** Python, JavaScript, HTML, CSS
- **Frameworks:** Angular, Node.js
- **Cloud Services:** AWS
## Experience
I have worked on various projects ranging from web development to cloud architecture. Here are some highlights:
### Cloud Application Architect @ Amazon Web Services
**Dates Employed: December 2021 - Present**
- Architect and modernizing customer applications to be cloud optimized.
- Advise and implement Cloud best practices.
- Implement DevOps practices such as infrastructure as code, continuous integration and automated deployment.
- Python, NodeJs and Java Development.
- Serverless Development.
## Projects
### Cloud Resume Challenge
A brief description of Project Name 1. [GitHub Repo](https://github.com/username/project1)
## Blog
I enjoy sharing my knowledge and experiences through blog posts. Check out some of my latest entries:
### [How I Built This Website](myblog1.md)
A detailed explanation of how I created this personal website using MkDocs and Markdown.
### [Lessons Learned from the Cloud Resume Challenge](myblog2.md)
Insights and takeaways from completing the Cloud Resume Challenge.
## Contact
Feel free to reach out to me via [email](your-email@domain.com) or connect with me on [LinkedIn](https://www.linkedin.com/in/your-profile).
---
By updating the `index.md` file, we enhance the website's content and layout, making it more informative and visually appealing. Adding sections like Experience, Projects, and Blog, along with some styling elements, helps create a professional and engaging personal website.Enhancing the Website with a Theme
Although the website looks nice, we can make it look even more professional by adding a theme.
By default, MkDocs includes two built-in themes: mkdocs and readthedocs. However, many third-party themes are available to choose from as well. You can see a list of themes here.
Let’s use the material theme. To do this, first, run the following command to install the Material theme:
pip install mkdocs-materialNext we need to add the following code inside the mkdocs.yml file:
theme:
name: 'material'Here’s what your mkdocs.yml file looks like so far:
site_name: Carlos Cano Personal Website
site_url: https://yourdomain.com/
nav:
- Home: index.md
- Experience: experience.md
- Projects: projects.md
- Blog:
- Blog1: myblog1.md
- Blog2: myblog2.md
theme:
name: 'material'Now our website should look like this:
It Looks Good, Now What?
Now that your website is looking good, what’s the next step?
First, let’s build the website by running the following command:
mkdocs buildThis command will create a new directory named site. Take a look inside the directory.
Notice that your website has been output as HTML files, such as index.html and about/index.html. Additionally, various other media files have been copied into the site directory as part of the documentation theme.
You’ll also find a sitemap.xml file and mkdocs/search_index.json.
The documentation site that you just built only uses static files, so you’ll be able to host it from pretty much anywhere.
Simply upload the contents of the entire site directory to wherever you're hosting your website, and you're done.
For specific instructions on a number of common hosts, refer to the Deploying your Docs page: https://www.mkdocs.org/user-guide/deploying-your-docs/
Hosting Options
Here are some popular options for hosting your MkDocs site:
1. GitHub Pages: You can host your MkDocs site directly on GitHub Pages. This is a free and easy option, especially if your project is already on GitHub.
2. Amazon S3: Another great option is to host your MkDocs site in an Amazon S3 bucket. S3 provides a highly scalable, reliable, and low-latency data storage infrastructure. You can configure your S3 bucket to serve static website content, making it a good fit for your MkDocs site.
3. GitLab Pages: If your project is hosted on GitLab, you can use GitLab Pages to host your MkDocs site. This service offers a straightforward way to publish static websites directly from a GitLab repository.
Now you have a fully functional, professional-looking personal website.
Enjoy showcasing your resume and projects in style!
Cloud Resume Challenge
As a big fan of the Cloud Resume Challenge, I can attest to how valuable it is for learning and improving your skills in cloud technologies.
The challenge involves creating a personal resume website and deploying it on the cloud, incorporating various cloud services and best practices along the way. Completing the Cloud Resume Challenge was a transformative experience for me, as it pushed me to learn about AWS, infrastructure as code, CI/CD pipelines, and more.
The Cloud Resume Challenge is a fantastic way to gain practical experience and demonstrate your cloud skills. It also highlights the importance of having a well-designed and professional-looking personal website.
Using MkDocs and a theme like Material, you can create a stunning online resume that showcases your achievements and expertise. If you’re interested in cloud technologies and want to take your skills to the next level, I highly recommend taking on the Cloud Resume Challenge!
