-
Notifications
You must be signed in to change notification settings - Fork 2
release 0.1
September 18th by midnight.
You are tasked with building a simple a command-line tool for authoring "Today I Learned" posts in Markdown, which can be converted to HTML for publishing on the web.
"Today I Learned" or TIL as it's more commonly known, is a post format in which the author shares something they've learned about a topic. Programmers and open source developers often use them to leave notes to themselves and others about concepts, technologies, and patterns they discover in their work.
Simon Willison is a prolific open source developer, blogger, and TIL author, and describes them like this:
A TIL—Today I Learned—is the most liberating form of content I know of.
Did you just learn how to do something? Write about that.
Call it a TIL—that way you’re not promising anyone a revelation or an in-depth tutorial. You’re saying “I just figured this out: here are my notes, you may find them useful too”.
I also like the humility of this kind of content. Part of the reason I publish them is to emphasize that even with 25 years of professional experience you should still celebrate learning even the most basic of things.
I learned the “interact” command in pdb the other day! Here’s my TIL.
I started publishing TILs in April 2020. I’m up to 346 now, and most of them took less than 10 minutes to write. It’s such a great format for quick and satisfying online writing.
My collection lives at https://til.simonwillison.net/—which publishes content from my simonw/til GitHub repository.
Imagine that you've spent the day researching some topic, and have loose notes, some screenshots, and a few snippets of code. You'd like to turn this into something you can post on the web without having to author HTML manually. Your TIL tool will allow you to enter a simple command that will convert everything to .html output file.
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 the freedom to work on real open source projects, but this first one is designed to give you a specific set of experiences.
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 static site generation, blogging, Markdown, HTML
- 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 tool 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 and 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
tilfor 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. GitHub README files are written in Markdown, which is a format you need to become comfortable using.
-
choose a programming language. You can use any language you want: pick one 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. Students in previous semesters have used JavaScript, TypeScript, Python, C++, Go, Rust, Ruby, etc.
-
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:
til ./file.txt
til ./folder-nameIf the input is a .txt file, it should process that file; if it's a directory, your tool should look for and find all .txt files within that folder, processing each one.
- 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 write output file(s) to a
./tilfolder by default. That is, if I run the tool, I should end-up with a new folder calledtilin the current directory, and it should contain one or more.htmlfiles. Each time the tool is run, an existingtilfolder should first be removed so thattilalways contains the latest output.
In addition to the required features, you are asked to pick at least 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,tilwill be used, but if the user specifies a different output path, use that. Your program should create the directory if it does not exist. -
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:til -s https://cdnjs.cloudflare.com/ajax/libs/tufte-css/1.8.0/tufte.min.css notes.txtortil -s https://cdn.jsdelivr.net/npm/water.css@2/out/water.css notes.txt -
if the user specifies a folder as input, do a recursive search for
.txtfiles and re-create this directory hierarchy in the output directory. -
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.
-
generate social media sharing and SEO
<meta>tags and allow the user to include command-line args to populate this info (e.g.,--author,--image, etc) -
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
- GitHub Repo contains an
examples/directory with some sample/test TIL posts - 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 and include it in an examples/ folder in the repo. Use your work on this release to write some TIL posts, sharing things you learn as you work.
When you are ready to submit, generate a web site with tool post it somewhere on the web (e.g., Vercel, Netlify, GitHub Pages, Glitch, etc) Only host the built, static HTML, not the server itself. 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.