Special Notes §
As the project is in its early stage, this documentation will update gradually in the future.
Table of Contents §
- User Guide
Every developer 🧑🏼💻 needs an awesome place to exhibit their unique efforts and inspirations, bringing them all over the world 🌏. Natalia may be a good choice for you to build up your own portfolio and blog site in a few minutes, and deliver your ideas in a friendly way. Out of the box, easy configuration, and free customization.
- Google Fonts
- Microsoft Clarity
Natalia is born in the free world of open-source software.
Already here §
There are several main features of Natalia:
- A portfolio home page showing your basic information (and logo), pinned projects, and pinned posts.
- A projects list page listing all your projects and efforts, along with detail pages of every project.
- A posts list page listing all your posts and ideas, along with detail pages of every post. Within every post, comments are supported with the help of Gitalk.
- A contact page where visitors can send you emails via email service provided by EmailJS
Natalia supports a wide range of Markdown contents including:
- Inline and block code highlighted by HighlightJS.
:+1:👍 supported by jemoji.
- LaTeX contents including inline notations and block equations rendered by MathJax.
Natalia also supports awesome features provided by third-party libraries:
- Embedded comments plugin using GitHub Issues and Preact powered by Gitalk. No additional server-side applications are needed.
- Direct email plugin provided by EmailJS where users can send you emails without opening email clients.
- Clear site analysis with the help of Microsoft Clarity which enable the global monitoring and statistic of your site. Totally free and easy to use.
Many other features are included in Natalia as well, such as the global dark mode.
To find all the Natalia’s features, please refer to the CHANGELOG.
Coming soon §
Natalia is far from a perfect project right now. Quite a few features are about to be considered:
- Group projects and posts by tags in standalone pages.
- Add more components to the portfolio home page, such as detailed self-introduction, personal experiences, and programming skills.
- Maybe add a timeline to the posts page.
- Improve the appearance and behavior of the contact page. Maybe add more components to provide more information and contact methods.
You can find all the Natalia’s scheduled backlogs from here.
User Guide §
All the customization can be made just inside the
_config.yaml file, but you can also customize more by editing the source code.
Personal information settings §
There is some information you can add to Natalia in the section
Personal information settings of the
You can add your name, your description, and your social media accounts & channels.
Natalia currently only supports Email, Twitter, Facebook, Instagram, YouTube, and GitHub. But it is quite simple to add more social media like Stack Overflow or Vimeo to Natalia by yourself. Just need a few Web skills.
Additionally, you can also edit the base title of windows and the copyright information in the footer.
Basic building and deploying settings §
There are more configurations of how the site is built and which component is enabled in the section
Basic building and deploying settings of the
baseUrl: You should modify the
urlto your custom domain name because the functions of some plugins rely on it. For more information about the
gitalk: Gitalk is a lightweight comment component based on GitHub Issues and Preact. You can enable the comment function of your site in a few minutes. For more information about the setup procedure of Gitalk, please refer to its usage. You should just modify the fields like
gitalk.repoto the corresponding values you configured.
clarity: By Microsoft Clarity, you can easily monitor your site and get key indexes of visitors. Like Gitalk and EmailJS, just create an account and a project, and add the project ID to the
projectIDfield. You can also indicate whether you want to enable this feature by setting the
Leaking sensitive information like
gitalk.clientSecretto the public if you modify the field directly in your repo may be vulnerable. A better way to configure such fields is to expose the corresponding values to environment variables in your CI or hosting system, and inject these values when building the site. Most CI and hosting systems, including GitHub Pages (as it is based on GitHub Actions) support the environment variable injection. Please refer to their documentation for more information.
Advanced building and deploying settings §
There are some advanced configurations of Natalia in the section
Advanced building and deploying settings section of the
In most cases, DO NOT modify contents in this section unless you are clear about what you are doing.
You can deploy Natalia manually on your Virtual Machines provided by Cloud Service Providers like AWS, Azure, and Google Cloud. Besides, you can also deploy Natalia using the static page hosting services provided by GitHub Pages, Azure Static Web Apps, Cloudflare Pages, and AWS Amplify.
Deploying manually §
Clone this project.
$ git clone https://github.com/Hyperzsb/natalia-theme.git $ cd natalia-theme
- Customize your awesome site. For more details, please refer to Customization.
Install dependencies using
bundle. For more information about installing bundle and Jekyll, please refer to Quickstart Guide of Jekyll.
$ bundle install
$ bundle exec jekyll build
- Copy the build output inside
_site/directory to the corresponding folder of your server (like Nginx and Apache) to publish it. For more information about the server applications, please refer to their documentation.
Deploying using GitHub Pages §
- Fork, clone this repo, or use this repo as the template.
- Customize your awesome site. For more details, please refer to Customization.
- Modify the
baseUrlfield in the
_config.yamlfile. Typically, if you use GitHub Pages to deploy your site, the site will be deployed under a non-root route of the domain provided by GitHub Pages or your custom domain. For example, assuming you are using the domain provided by GitHub Pages,
hyperzsb.github.io, this site will be deployed under
hyperzsb.github.io/natalia-theme. To avoid potential route issues, you should modify the
baseUrlfield with the value
/natalia-theme. To learn more about this modification, please go through the Troubleshooting section.
- Go to the setting page of your repo, and enable the GitHub Pages service. For more details about how to enable the GitHub Pages, please refer to its documentation.
- You can visit your site once the deployment has succeeded.
Here is a live demo of deploying Natalia using GitHub Pages: demo.
- Invalid Ruby version
Although the preferred Ruby version is
~> 3.0, lower LTS versions are also acceptable (e.g.
However, if you choose to use a lower version other than
~> 3.0, you should modify the
Gemfile to remove version flags of Jekyll gems to achieve maximal compatibility.
Additionally, in this situation,
Gemfile.lock should be removed as well.
This problem is probably caused by assigning an empty or incorrect value to the
baseUrl field in the
When you deploy your site under a non-root route of a given domain (for example,
https://hyperzsb.github.io/natalia-theme), you may encounter this problem.
In this situation, if no modification has been made to the
baseUrl field, the browser will attempt to download CSS, JS, and other assets (like images) from the root route (in this example,
https://hyperzsb.github.io) rather than the actual route (
To deal with this problem, just modify the
baseUrl field to the corresponding value (in this example, modify it to
/natalia-theme) and redeploy your site.
Additionally, for senior users, you can just config redirect rules on your Apache and Nginx servers (if you deploy your sites manually); or you can just add some rewrite/redirect rules to your service providers (if you deploy your sites using some hosting services). No need to modify the
It is a more complicated way, but may offer more flexibility.
Natalia welcomes any contributions from anyone! Please make Natalia a better tool for every developer!
This project is under MIT License.