Building a "Today I Learned" (TIL) Tool in Python

Introduction

In the realm of programming and open source development, the concept of "Today I Learned" or TIL posts has gained significant popularity. These posts serve as a means to share bite-sized nuggets of knowledge and insights discovered during various technical endeavors. Beyond its utility in disseminating knowledge to others, TIL posts also serve as personal repositories of learning for future reference.

This article embarks on the journey of constructing a straightforward command-line TIL tool in Python. The tool's primary function is to transform Markdown files into HTML format, facilitating the sharing of newfound wisdom on the web.

Prerequisites

Before we dive into the technicalities, let's ensure we have the prerequisites in place:

• A working installation of Python.
• A fundamental grasp of Python programming.
• Familiarity with Markdown, a lightweight markup language.

Step 1: Language Selection

Our first task involves choosing an appropriate programming language for our TIL tool. We've opted for Python, primarily due to its simplicity and the availability of libraries catering to Markdown and HTML processing. However, you're welcome to use a language of your preference if you're more comfortable with it.

Step 2: Project Initialization

To kickstart our project, we initiate a GitHub repository to facilitate version control and collaboration with fellow developers. If you're new to GitHub, don't worry; you can refer to GitHub's comprehensive guide on creating a new repository.

Upon establishing the repository, it's essential to include a license file (e.g., MIT) and craft a detailed README.md to comprehensively document the project's purpose and usage.

Step 3: Implementing Core Functionality

The heart of our TIL tool revolves around executing the following key functions:

1. Parsing command-line arguments to specify input files and output folders.
2. Reading the content of input Markdown files.
3. Transforming Markdown to HTML using the markdown library.
4. Writing the HTML content to corresponding output HTML files.

Our Python script encapsulates these functionalities. Here's a simplified version:

import os
import argparse
import markdown

# Function to convert Markdown to HTML
def convert_to_html(markdown_text):
    # Convert Markdown to HTML
    html_content = markdown.markdown(markdown_text)
    return html_content

# Function to process a single input file
def process_file(input_file, output_folder):
    # Read the content of the input file
    with open(input_file, 'r') as file:
        markdown_text = file.read()

    # Convert Markdown to HTML
    html_content = convert_to_html(markdown_text)

    # Create the output file path
    input_filename = os.path.basename(input_file)
    output_file = os.path.join(output_folder, input_filename.replace('.txt', '.html'))

    # Write the HTML content to the output file
    with open(output_file, 'w') as file:
        file.write(html_content)

# Main function
def main():
    # Parse command-line arguments
    parser = argparse.ArgumentParser(description='TIL Tool - Convert Markdown to HTML')
    parser.add_argument('input', help='Input .txt file or folder of .txt files')
    parser.add_argument('-o', '--output', default='til', help='Output directory for HTML files')
    args = parser.parse_args()

    # Create the output folder if it doesn't exist
    os.makedirs(args.output, exist_ok=True)

    # Process the input (file or folder)
    if os.path.isfile(args.input):
        process_file(args.input, args.output)
    elif os.path.isdir(args.input):
        # Process all .txt files in the input folder
        for filename in os.listdir(args.input):
            if filename.endswith('.txt'):
                input_file = os.path.join(args.input, filename)
                process_file(input_file, args.output)

if __name__ == '__main__':
    main()

Step 4: Incorporating Optional Features

While our TIL tool covers the essentials, it can be further enriched with optional features. These include the ability to specify a custom stylesheet, handling titles, and enhancing the visual appeal of generated HTML pages. Depending on your preferences and project goals, you can choose from these optional features provided in the assignment.

Step 5: Testing the TIL Tool

Before sharing your TIL tool with others, rigorous testing is imperative. Create sample TIL posts in Markdown format, and employ your tool to convert them to HTML. It's vital to verify that the generated HTML aligns with your expectations.

Step 6: Documentation and README

A meticulously documented project is indispensable for open source development. Elevate your project's README.md to offer precise instructions on how to harness your TIL tool. Include comprehensive details regarding available features, command-line arguments, and illustrative examples.

Step 7: Publishing Your TIL Posts

Once your TIL tool is fully operational, commence composing TIL posts. Establish a dedicated folder for your TIL posts, pen them in Markdown, and utilize your tool for the transformation into HTML. Subsequently, you can broadcast these HTML files on a website, blog, or platform of your choosing.

Conclusion

Building a Python-based TIL tool is an excellent conduit for disseminating knowledge and discoveries within the community. This project imparts valuable insights into open source development conventions, command-line utilities, and Markdown-to-HTML conversion. Personalize and enhance your tool to augment its utility for your TIL posts.

Happy TIL-ing!