Bounty 1: Cape Software Community static website creation

[BenSchZA]

Bounty

Bounty Description

This is the first bounty for the Cape Software Community! Typically, projects will create bounty programs called "Bug Bounties"—a reward for discovering software bugs. Here, we want to create bounty programs for new software developers to learn the ropes of contributing to open-source software and receive guidance and mentorship along the way. In future, we may expand the program to allow others to post or sponsor bounties.

The bounty program will work as follows:

1. Bounties will be posted as GitHub issues
2. New software developers will be asked to submit a proposal as a comment on the issue indicating how they intend to complete the bounty
3. The issue creator will review and accept one of the proposals
4. Successful completion of a bounty is rewarded, judged by the issue creator according to the "definition of done"

Bounty Milestones and Rewards

The reward for this first bounty is allocated according to specific milestones as follows:

1. Deployment of the website to GitHub Pages: 15 USD
2. Publication of first technical blog post: 15 USD
3. Continued management of the blog, including getting 1 new guest blog post per month from someone in the community: 15 USD

Bounty Sponsorship

If you're interested in sponsoring this ongoing or future bounty, become a GitHub Sponsor or reach out!

Context and Assumptions

Include necessary background information to complete the task, including links to existing discussions such as Slack threads or external resources

Currently, the blog is hosted using Ghost on Digital Ocean and can be accessed at https://www.capesoftwarecommunity.co.za. It is managed by the Cape Software Community, which hosts meetups in Cape Town. The community is a space for new and experienced developers to share knowledge and ideas and meet new people in the industry in person.

To make the website more developer-focussed and community-managed, we'd like to migrate the website to a static website initially hosted on GitHub Pages and, in future, on the original domain name, possibly using CloudFlare Pages (future scope).

Specification and Scope

Specify the task or technical specification as SMART goals, including both what is and isn't in scope

1. A static website generator framework should be selected to allow us to:
   • Generate blog posts from Markdown
   • Tag blog posts (e.g. #python, #ideas, etc.)
   • Display blog post authors
   • Display images in a gallery (see current website)
   • Allow commenting (maybe Disqus) and sharing of content (i.e. blog posts should be populated with the necessary metadata to be shared on social media with previews etc.)
2. The existing content should be converted to Markdown
3. Tests should be executed on new PRs using GitHub Actions
4. A new technical blog post should be written about a software development topic of your choice with yourself as the author
5. The website should be deployed using GitHub Pages at https://capedevs.github.io

Please share your top 3 frameworks and the motivation for each as a comment on this issue before continuing with the implementation.

User Stories

Expand on the task or technical specification by writing User Stories where appropriate

Acceptance Criteria and Testing

Add a "definition of done" i.e. some way to test that the task has been completed successfully; in the case of code this can be actual tests to be executed or validation of output to be done

1. All existing content has been converted to Markdown with appropriate tags, images, etc.
2. A GitHub Action has been created that is executed for every new PR to test for the successful generation of the static website
3. The website is deployed on GitHub Pages after a new PR is merged that passes the GitHub Action tests
4. A new technical blog post has been published

[smngvlkz]

Proposal

I would like to submit my proposal for the Cape Software Community Bounty Program. I am a junior, and I am eager to contribute to open-source software and learn more about the development process.

Approach

Static Website Generator Selection: I propose using Next.js for this project. A powerful React framework that supports static site generation and has excellent community support. With its excellent performance and built-in support for static site generation.

My other two frameworks are:

Gatsby: It has a rich plugin ecosystem, useful for extending functionality.

Hugo: For its speed and simplicity.

Content Migration: I will meticulously convert all existing content into Markdown format, ensuring preservation of tags, images, author details, and other relevant metadata.

Testing and Deployment: Using GitHub Actions, every new PR will trigger a build and test sequence to ensure the static site generates successfully. Upon passing these tests, the site will be deployed to GitHub Pages at https://capedevs.github.io

New Content Creation: I will write a technical blog post on a topic of my choice, ensuring it is informative, engaging, and beneficial to the community.

In addition to these, I will explore options for implementing a comment feature, such as Disqus, and ensure that blog posts have necessary metadata for effective sharing on social media platforms.

I am ready to start working on this bounty and look forward to contributing to the Cape Software Community.

[BenSchZA]

Hey @smngvlkz, thanks for submitting a proposal! Although initially, I thought that a simpler static blog framework like Jekyll (GitHub's choice) or Hugo may be better because they are simple and come out-the-box with Markdown and blogging support, having the flexibility of Next.js means that it can be extended and will be a learning experience for any future contributors to the website.

As a follow up to this proposal, before getting started, could you do some quick research on Next.js Markdown blogging best-practises and make a suggestion about what the best approach is? For starters: https://nextjs.org/docs/app/building-your-application/configuring/mdx, https://vercel.com/templates/next.js/blog-starter-kit. I think a requirement if we do choose Next.js over, for example, Jekyll or Hugo is that it should be straightforward for someone to create a Markdown file and add the necessary blog post tags without having to know HTML, JS, CSS or editing any of that code.

[smngvlkz]

@BenSchZA,

Thank you for your feedback. I agree that the simplicity of creating and managing blog posts is crucial for this project. After researching, I found that Next.js can indeed support a straightforward Markdown blogging system.

One approach is to use next-mdx-remote package. This allows us to source Markdown files from the filesystem and render them as Next.js pages. We can add frontmatter to our Markdown files to include metadata like title, author, and tags. There are great tutorials out there to help us achieve this.

Another approach is to use gray-matter and remark libraries. gray-matter is used to parse the frontmatter from our Markdown files, and remark is used to convert the Markdown into HTML. This blog starter kit you mentioned uses this approach.

Both methods allow us to create blog posts by simply adding a new Markdown file with the necessary frontmatter, without needing to touch any HTML, JS, or CSS. I believe this meets the requirement you mentioned.

I was leaning towards the next-mdx-remote approach because it allows us to use React components within our Markdown files, providing more flexibility for future enhancements.

I also want to add that I initially suggested Next.js because I'm more familiar with it. However, I'm open to using Jekyll or any other static site generator that you think would be a better fit for this project. My main goal here is to learn and contribute to the Cape Software Community. I'm ready to adapt and learn new technologies as needed.

[BenSchZA]

I think that sounds like a great plan @smngvlkz. I've assigned the task to you 🎉 Please keep us up to date as you progress and check in if you have any questions or concerns.

[smngvlkz]

@BenSchZA I have successfully built the Cape Software Community website into a static site, converting existing content into Markdown format. I also enhanced the design with personal styling touches, improving the overall user experience.

Instead of just publishing a single blog post, I took an extra step and created a new Blog page. This page serves as a hub for all blog posts, making them easily accessible to the community.

I integrated Disqus and React-share for commenting and sharing functionalities. Now, users can engage more interactively with the blog posts and share them within their networks.

As per Disqus requirements, I have taken on the role of comment moderator. This ensures the site’s management for the long term.

To help users and other developers navigate and contribute to the site, I wrote comprehensive documentation.

I have added a GitHub Actions workflow to automate the build and export process of the site. This ensures that the site is consistently built and deployed, making it easier for other contributors to make changes without worrying about the deployment process.

I believe I have not only met but exceeded the scope of the bounty, and I owe a great deal of my success to your guidance as a mentor. I thoroughly enjoyed working on this project, and I am eager to continue contributing. I appreciate your consideration for the reward allocation as outlined in the bounty milestones.

[BenSchZA]

@smngvlkz thanks for the update!

I'd suggest the following tasks to complete the bounty:

• The blog posts should have an image gallery feature that adapts appropriately depending on how many images are displayed—currently, it's a screenshot of a grid of images, which relies on the developer to generate and will not be mobile-friendly
• The read more section should be automatically generated / not hard-coded (e.g. latest 3 posts)
• Remove the Blog page, it's not clear why it's required as it provides the same functionality as the landing page
• Remove the wrapper card around the cards—it's not typical to have two layers for a card

The original bounty allocation included the publication of a technical blog post and continued management of the blog, but if the above features are completed, I'd be happy to award the full bounty of 45 USD for the development and deployment of the blog website.

The reward for this first bounty is allocated according to specific milestones as follows:

Deployment of the website to GitHub Pages: 15 USD Publication of first technical blog post: 15 USD Continued management of the blog, including getting 1 new guest blog post per month from someone in the community: 15 USD

[smngvlkz]

@BenSchZA, thanks for your feedback. I always appreciate your clear guidance and goals. Just to update you, I've completed all the tasks and features you requested. The only thing I still need is access to the original site's images, as I had to use a screenshot without them. The gallery feature works well and is user-friendly.

The read more section is now automatically generated and not hard-coded anymore.

The blog page has been removed.

The site is also now live on GitHub pages from my forked repo as a test. You can view and play around with it. If you are happy and approve the PR, the workflow will be automatically triggered to deploy from the main branch.

I will be responsible for managing the site, and I will set up a staging environment after approval to help with managing the site.