Natalia is a flat, content-focused, easy-to-use template portfolio and blog theme powered by Jekyll and Bootstrap.
As the project is in its early stage, this documentation will update gradually in the future.
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.
Natalia is mainly developed on Jekyll and Bootstrap, but lots of JavaScript libraries, Ruby gems, Liquid templates, and third-party APIs are used as well (in lexicographical order):
Natalia is born in the free world of open-source software.
There are several main features of Natalia:
Natalia supports a wide range of Markdown contents including:
:+1:
👍 supported by jemoji.Natalia also supports awesome features provided by third-party libraries:
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.
Natalia is far from a perfect project right now. Quite a few features are about to be considered:
You can find all the Natalia's scheduled backlogs from here.
All the customization can be made just inside the _config.yaml
file, but you can also customize more by editing the source code.
There is some information you can add to Natalia in the section Personal information settings
of the _config.yaml
file.
You can add your name, your description, and your social media accounts & channels.
Natalia currently supports Email, Facebook, GitHub, Instagram, Linkedin, Stack Overflow, Twitter, WhatsApp, and YouTube. And it is quite simple to add more social media like Vimeo to Natalia by yourself with a few Web skills.
Additionally, you can also edit the base title of windows and the copyright information in the footer.
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 _config.yaml
file.
url
and baseUrl
: You should modify the url
to your custom domain name because the functions of some plugins rely on it.
For more information about the baseUrl
, please refer to Can not download CSS, JavaScript, or other assets from the server (404 error) in the section Troubleshootinggitalk
: 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.clientID
, gitalk.clientSecret
, and gitalk.repo
to the corresponding values you configured.emailjs
: EmailJS provides front-end email service by JavaScript in the contact page.
Just like Gitalk, set up your account, service, and template following its documentation and add the values to the corresponding fields.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 projectID
field.
You can also indicate whether you want to enable this feature by setting the enable
field to true
or false
.Leaking sensitive information like
gitalk.clientSecret
to 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.
There are some advanced configurations of Natalia in the section Advanced building and deploying settings
section of the _config.yaml
file.
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.
My home site hyperzsb.io is currently hosted on AWS Amplify.
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
Build Natalia.
$ 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.
As Natalia is developed atop Jekyll, you can easily deploy your awesome site using GitHub Pages.
baseUrl
field in the _config.yaml
file.
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 baseUrl
field with the value /natalia-theme
. To learn more about this modification, please go through the Troubleshooting section.Here is a live demo of deploying Natalia using GitHub Pages: demo.
Although the preferred Ruby version is ~> 3.0
, lower LTS versions are also acceptable (e.g. 2.4
and 2.6
).
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 _config.yaml
file.
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 (https://hyperzsb.github.io/natalia-theme
).
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 _config.yaml
file.
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.