Skip to content
This repository has been archived by the owner on Aug 5, 2022. It is now read-only.

Latest commit

 

History

History
427 lines (344 loc) · 19.9 KB

README.md

File metadata and controls

427 lines (344 loc) · 19.9 KB
Raw

👨‍💻 Somraj Saha's Blog.

Website Netlify Deploy LinkedIn Quora profile Ask Me Anything ! Twitter Follow

DISCLAIMER: I'M NO LONGER MAINTAINING THE PROJECT!

The repository & the project is abandoned! I'm no longer actively maintaining & working on this project since I recreated it using Next.js instead. If you're interested in checking it out, please head over to my personal website's repository. The project uses the latest features of React.js and is faster than a traditional Hugo project. So, feel free to check it out & contribute to it!

This repository hosts the tools, assets & themes for my personal website. The site is statically generated with Hugo & the PaperMod theme. Hugo which is a Static Site Generator(SSG) built with Golang generates the static contents for the site to be deployed to Netlify.

🏁 Getting Started

Did you find my website somehow either on GitHub or elsewhere on the Internet? Do you want a site similar to mine for yourself too? Or perhaps, you just ❤️ open-source software & would like to make a contribution to my site, then read this README should be your first step.

A bird's eye overview of what the blog is capable of:

  • It's FREE, as in no server costs are involved (for now).
  • In context to the point above, there's no server in the first place to serve the website on the Internet. All the generated static content are delivered over Netlify's CDN.
  • Transparency is a major aspect in everything I do in life. The same applies to my personal website as well. That said, I try to keep stuff related to it as open-source as possible on this repository. In other words, my website will forever be open-sourced.
  • My site uses Cloudflare Analytics along with Google Analytics (GA) for the following reasons:
    • Cloudflare is more privacy driven & hence is suitable for some of my more privacy-concerned audiences.
    • I would love to use Matomo over GA but it requires me to rent out a VPS. I just don't have the financial overhead to increase my expenses at the moment. So, as much as I want to protect my user's privacy, it's just not a possibility right now. Although, I appreciate every bit of a donation that will help me setup & maintain a Matomo Analytics server to protect your privacy.
    • Cloudflare Analytics is still in beta & doesn't offer as many metrics as GA provides. Much of the metrics I need, is important for me to keep improving the services I provide on my site & to my sponsors.
  • Knowledge-sharing over aesthetics. Visit my site & you'll find it's pretty simple & minimalist. That's intentional as I want my audiences to read my content & take home some valuable lessons. Intrusive popups & marketing gimmicks aren't my thing, so I try to keep that away from my personal site.
  • Make it a Wordpress alternative. Hence, it even supports an admin panel powered by Forestry.io!

So, if the aforementioned points matters to you, then fo ahead & check out how to get your own blog which looks similar to mine.

🏃 The Easy & Quick Way To Get It Done

In a hurry to get your personal website running ASAP, then check out the following section.

🔩 Setup a Development Environment

  1. Fork the repository.
  2. Clone your copy of the repository locally using the command git clone git@github.com:<INSERT_YOUR_USERNAME_HERE>/blog.git.
  3. Remove the files under the directory content. Note, the files are written in Markdown. So, if you've been active on GitHub for a while, writing your .md content will be a breeze.
  4. Ensure you've Hugo installed & is available on PATH. If not, then follow the instructions available in the official documentation to set it up on your local machine.
  5. Clone the PaperMod theme under the ./theme/ directory with the git submodule add https://github.com/adityatelange/hugo-PaperMod.git command.
  6. cd back into the root directory & run the hugo server command on your preferred terminal & see if everything works as expected.

📈 Setting Up Traffic Tracking & Analytics

The blog uses Cloudflare's tracker along with Google Analytics (GA). Thus, privacy-concerned users can either use uBlock Origin to block tracking JS code or block trackers & cookies from the browser. Using both of them in tandem also helps keep a check on certain inconsistencies (source).

That said, following are the instructions to setup Cloudflare (and/or GA):

Cloudflare
Google Analytics

  • Create a Google Analytics if you don't own one already!

  • Create the Google Analytics 4 property for the website.

  • Add the tracking code (which looks something like G-XXXXXXXXX) in the config.yml to the GoogleAnalyticsID key.

  • Add the gtag.js snippet to extend_head.html partial under layouts/partials.

    <!-- Global site tag (gtag.js)-->
<script async src="https://www.googletagmanager.com/gtag/js?id={{ .Site.Params.GoogleAnalyticsID}}"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag() { dataLayer.push(arguments); }
  gtag('js', new Date());

  gtag('config', '{{ .Site.Params.GoogleAnalyticsID}}');
</script>
<!-- End of Global site tag (gtag.js)-->

  • Check your GA dashboard with tracking cookies & JS enabled on your browser.

And you're good to go!

But in case, you've privacy concerns on using GA, refer to the Privacy Policy document for a detailed description of how we use the data gathered through the trackers.

NOTE: As of Hugo 0.80, the new Google Analytics 4 doesn't work out-of-the-box with Hugo's internal templates.

🎛️ Setup a CMS

Note: I'm in favour of using Forestry.io's service right now over Netlify CMS. It's much more easier & intuitive (and less buggier too) to setup. The decision was made after coming across a blocker as documented in #40. Since, the devs of Netlify haven't shown any interest to fix the issue, Forestry is a better choice.

For a detailed installation process, refer to the official Forestry.io documentations. The devs did an amazing job articultating the exact procedure to set it up.

That said, following are the advantages of get setting up a CMS admin panel on the site:

  • You no longer need a Markdown Editor (or even the development environment) installed locally. Just access it at: https://<YOUR-SITE>/admin & start writing.
  • You can give editorial access to 2 more writers all for free. More than that you would've to purchase a subsciption.
  • Forestry leverages the Git-backend to update any config files it needs for the CMS, on your behalf. All you got to do is tweak the settings on it's web-based GUI.
  • And finally, the main reason for switching from Netlify CMS to Forestry, availability of remote media storage. As of the now the site is configured to load up the image assets off of Cloudinary but other options include S3 & Netlify Large Media. These options should help me in case I need to scale up my image storage capabilities.

There's more information available on the official docs, so do check it out. They did a convincing job to make me switch.

💨 Preparing Your Site For Deployment

  1. Write your articles inside the ./content directory & save them as .md files. Check if the articles are generated as expected by running the hugo server command.
  2. Push your changes to GitHub with the git push command from the root directory.
  3. Create/login into an account on Netlify.
  4. Refer to the Netlify Documentations to setup an initial deployment. You'll have to do it only once if you want to deploy your changes with GitHub Actions instead just like me.
  5. Once the site is deployed, Netlify assigns a domain automatically. It should look something on these lines: https://<NETLIFY_GENERATED_ALPHANUMERIC_STRING>.netlify.app.

⚙️ Setup GitHub Actions to Deploy

While you could push your changes to GitHub & Netlify will still trigger a build on their platform, but it's pretty inefficient & non-scalable. Reasons being:

  • Netlify has a limited 300 minutes compared to GitHub's insane 2000 minutes of build times. While it should suffice if you've just one site but you can chew through your quoate pretty quick once you start deploying more sites.
  • Hugo is fast (or rather the fastest SSG out there). It'll generate your static files in under 1ms. Couple it with a fast Action, you can deploy the generated files to Netlify's CDN in less than half a min! This comes handy when you're committing changes constantly & would like to preview a live version of the changes. Doing the same takes at least a min on Netlify's servers.
  • It's a more configurable way to deploy the contents.

And the list goes on. There really is no reason why shouldn't use GitHub Actions to deploy your site to Netlify (if you can, that is).

So without further ado, let's setup GitHub Actions to build & deploy the site to Netlify (finally! 😤)

  • The nwtgck/actions-netlify is used to manage the build & deployment process. If you had followed the steps till now, you might notice on the GitHub Action's tab that it failed (which is expected). To fix it you'll need an Netlify Auth Token & the Site ID.
  • You can find the Netlify Auth Token under the User Settings>Applications tab. While the Site ID can be found under the individual site's settings at: https://app.netlify.com/sites/<YOUR-SITE-NAME>/settings/general. The alphanumeric name under API ID is what you should be looking out for.
  • Copy those details & save them as Encrypted Secrets. Make sure to name them as NETLIFY_AUTH_TOKEN & NETLIFY_SITE_ID respectively for the Auth token & the Site ID.

And you're good to go! Write an article under the ./content directory & push them to the remote respository. Then watch your workflow build & deploy the site all under half a minute! 🤯

🛠️ Built With

The site is built using Hugo to generate static content. These contents are then deployed to Netlify to be delivered over Netlify's CDN. These are the primary 2 tools you will specifically need to build the website.

For more information on how to use these tools, refer to their respective documentations:

🏗️ Contributing

I'm no frontend mastermind, hence I often need a helping to fix something on the website. So, if you find something broken & a feature needing some improvement, don't hesitate to make a PR. All suggestions & PRs to improve this project are appreciated.

or, perhaps you're just looking to get your feet wet in the open-source community. Then this site will be a perfect opportunity for you. Besides, there's a reason why I've open-sourced this personal website! 😉

There's a comprehensive guideline in the CONTRIBUTING.md document. Refer to it for more details on contributing to the project.

👀 Issues

In case of a bug report, bugfix or a suggestion, please feel free to open an issue following the respective templates

📦 Pull Request

Pull Requests are always welcome & I'll review them as quick as possible. But for easier collaboration, please follow the specification provided in the PR template.

📝 License

All software used & the content I share are licensed under the T&Cs as stated below:

  1. All the literary content available under ./content/posts are licensed under the CC0-1.0 license.

  2. The repository also uses and/or contains software used to generate the static contents for the personal website. Following are the software as well as other related tools used & their licensings T&Cs.

    Software Licence T&Cs
    Hugo Apache-2.0
    Netlify Actions MIT
    Hugo-PaperMod theme MIT
    Netlify Netlify Terms of Service Agreement
    Git Checkout Action MIT
    Actions-Hugo MIT
    Automerge-Action MIT

✋ Get Help

Facing difficulties to deploy your site after forking this repository? Well then feel free to reach out to me. I'm available on Twitter & LinkedIn for a quick chat. But if you need a very comprehensive explanation on something related to this project check out the Discussion threads.

Or maybe your question isn't related to this project, then check out my Ask Me Anything.

👏 Acknowledgements