natalia-theme

Natalia is a flat, content-focused, easy-to-use template portfolio and blog theme powered by Jekyll and Bootstrap.

Special Notes

As the project is in its early stage, this documentation will update gradually in the future.

Table of Contents

• Introduction
• Features
  • Already here
  • Coming soon
• User Guide
  • Customization
    • Personal information settings
    • Basic building and deploying settings
    • Advanced building and deploying settings
  • Deploy
    • Deploy manually
    • Deploy using GitHub Pages
• Troubleshooting
• Contributing
• License

Introduction ^{Top ⥣}

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):

• EmailJS
• Gitalk
• Google Fonts
• HighlightJS
• jekyll-anchor-headings
• jekyll-feed
• jekyll-seo-tag
• jekyll-sitemap
• jekyll-toc
• jemoji
• Lodash
• MathJax
• Microsoft Clarity

Natalia is born in the free world of open-source software.

Features ^{Top ⥣}

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.
• Emojis like :+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 ^{Top ⥣}

Customization

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 _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.

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 _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 Troubleshooting
• 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.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.

Advanced building and deploying settings

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.

Deploying

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.

Deploying manually

1. Clone this project.

   $ git clone https://github.com/Hyperzsb/natalia-theme.git
   $ cd natalia-theme

2. Customize your awesome site. For more details, please refer to Customization.

3. Install dependencies using bundle. For more information about installing bundle and Jekyll, please refer to Quickstart Guide of Jekyll.

   $ bundle install

4. Build Natalia.

   $ bundle exec jekyll build

5. 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

As Natalia is developed atop Jekyll, you can easily deploy your awesome site using GitHub Pages.

1. Fork, clone this repo, or use this repo as the template.
2. Customize your awesome site. For more details, please refer to Customization.
3. Modify the 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.
4. 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.
5. You can visit your site once the deployment has succeeded.

Here is a live demo of deploying Natalia using GitHub Pages: demo.

Troubleshooting ^{Top ⥣}

• Invalid Ruby version

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.

• Can not download CSS, JavaScript, or other assets from the server (404 error)

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.

Contributing ^{Top ⥣}

Natalia welcomes any contributions from anyone! Please make Natalia a better tool for every developer!

License ^{Top ⥣}

This project is under MIT License.