release 0.1 - Seneca-CDOT/topics-in-open-source-2022 GitHub Wiki
Sunday September 18th by midnight.
You are tasked with building a simple Static Site Generator (SSG). An SSG is a tool for generating a complete HTML web site from raw data and files, without having to author any HTML by hand. Imagine that you have a folder of text files that you want to turn into a website. An SSG allows you to enter a simple command that creates .html output files from a given set of input files.
This first release is designed to expose you to the common workflows and tools involved in contributing to open source projects on GitHub. In order to give every student a similar learning experience, we will all be working on the same project.
This first release is also aimed at putting you in the role of "open source creator" and later "open source maintainer." You will use the code you write in this assignment in subsequent labs during the course to explore various aspects of open source work.
NOTE: in subsequent releases, you will have more freedom to work on different open source projects.
In addition to the actual code you will write, the ultimate goal of this first release is to help you gain experience in many aspects of open source development, specifically:
- gaining experience in a programming language by building a real-world tool (you can use any programming language you want, even one that's new to you)
- learning about SSGs
- working with the basics of git, including branches, commits, etc.
- creating open source projects on GitHub
- writing about your own work via your Blog
At first, your static site generator will have only a small number of features. Over time we'll add more.
For this first release, you are asked to create a command-line tool (e.g., no GUI, not a web app). Your command-line tool will process input .txt files into generated .html files.
To begin, your tool must include all of the following:
-
pick a name for your tool. Try not to pick a name that is already used by other projects. I'll call my tool
my-ssgfor the rest of this document (call yours something more creative!). -
create a GitHub Repo for your project, see https://docs.github.com/en/enterprise/2.15/user/articles/create-a-repo
-
choose an OSI Approved Open Source License for your project and include a LICENSE file in your repo, see https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/licensing-a-repository
-
create a README.md file, and keep it updated as you write your code, documenting how to use your tool, which features you include, etc. Your README file should tell users what your tool is for, how to use it, and give examples.
-
choose a programming language. You can use a language you know and love, or something new that you've never used before and want to learn. If you're studying a particular language in other courses, consider picking that one so you can get more practice with it. Or, if you want to add a new language to your resume, this is a good chance to practice.
-
running your tool at the command-line with the
--versionor-vflag should print the tool's name and current version. -
running your tool at the command-line with the
--helpor-hflag should print a standard help/usage message showing how to run the tool, which command line flags and arguments can be used, etc. -
your tool should allow the user to specify either a file or folder of files as input, using
--inputor-i:
my-ssg --input file.txt
my-ssg -i ./folder-nameIf the input is a folder, your tool should find all .txt files within that folder.
- your tool should generate one
.htmloutput file for each input file. For example, if I run the tool ondoc.txta newdoc.htmlfile will be generated.
The HTML file you generate must valid HTML5 file, for example:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Filename</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<!-- Your generated content here... -->
</body>
</html>NOTE: the original file(s) should not be modified, see below for information about where to place output file(s).
- you need to deal with marking-up paragraphs: every blank line should be considered a paragraph limit and the text transformed into
<p>...</p>. For example, given the following input file:
This is the first paragraph.
This is the second paragraph.
Should be transformed into:
<p>This is the first paragraph.</p>
<p>This is the second paragraph.</p>
- your tool should place all output into a
./distfolder by default. That is, if I run the tool, I should end-up with a new folder calleddistin the current directory, and it should contain one or more.htmlfiles. Each time the tool is run, an existingdistfolder should first be removed so thatdistalways contains the last output.
In addition to the required features, you are asked to pick 2 of the following optional features to include in your submission:
-
try to parse a title from your input files. If there is a title, it will be the first line followed by two blank lines. In your generated HTML, use this to populate the
<title>...</title>and add an<h1>...</h1>to the top of the<body>. -
allow the user to specify a different output directory using
--outputor-o. If not specified,distwill be used, but if the user specifies a different output path, use that. Print an error if the specified output path is not a valid directory. -
allow the user to optionally specify a
--stylesheetor-sURL to a CSS stylesheet to be used in the<head>of your generated HTML files. For example: https://cdnjs.cloudflare.com/ajax/libs/tufte-css/1.8.0/tufte.min.css or https://cdn.jsdelivr.net/npm/water.css@2/out/water.css -
allow the input to be a deep tree of files and folders. That is, if the user specifies a folder for
--input, check to see if any of the items contained within are folders and recursively parse those as well. -
if the user specifies a folder for the input, automatically generate an
index.htmlfile, which has relative links to each of the generated HTML files. -
improve the look and feel of your generated HTML pages using a default stylesheet that you design. Make them responsive, use beautiful fonts and colours, improve the layout and readability of the text.
-
come up with your own idea. If you have an idea not listed above, talk to your professor and see if it's OK to implement that (it probably is).
For this assignment, everyone must do their own work, but that doesn't mean you can't talk to your colleagues. At every stage of your work, make sure you ask for help, share ideas, and get feedback from others in the class. Please use Slack to help with communication.
Try using community-based, open, collaborative development practices. This means talking with others about your work, and talking to them about theirs, asking for and giving help, and focusing on people as well as code. It also means doing this in public (e.g., on Slack) instead of in private. The goal is to support each other and for us to start building a community.
You will be graded on the following. Please make sure you have addressed everything that makes sense below:
- GitHub Repo exists
- GitHub Repo contains LICENSE file
- GitHub Repo contains a README.md file with clear and complete information on the steps to use the tool, examples, and all of its features
- GitHub README.md is free of typos, spelling mistakes, formatting or other errors
- GitHub Repo contains project's Source Code
- Source Code implements all Mandatory Requirements, and each one is Complete and Working
- Source Code implements 2 of the Optional Requirements, and both are Complete and Working
- Source Code is well written (consistent formatting, code comments, good naming, etc)
- Blog Post documents the project, how to use it, which features it includes, and shows examples of how to use it
- Blog Post contains link to GitHub repo
- Add Info to Table Below
You should create your own small sample data to test your work. However, you should also use the Sherlock-Holmes-Selected-Stories I've made available for something larger. NOTE: I've intentional put spaces in the filenames to force you to write code that can handle paths that include spaces!
When you are ready to submit, generate a site from the Sherlock sample stories and post it somewhere on the web (e.g., Vercel, Netlify, GitHub Pages, Glitch, etc). Include a link in your submission to the generated static site.
When you have completed all the requirements above, please add your details to the table below.