kliu57 / go-go-web

Command-line tool that converts TIL posts into .html files.

go-go-web

Command-line tool that converts .txt or .md files into .html files.

Features

• v1.0.3 project package uploaded to PyPI
• v0.0.5 additionally parses front matter from .md files for metadata
• v0.0.4 additionally accepts TOML config file
• v0.0.3 additionally parses code blocks and horizontal rules for .md files
• v0.0.2 additionally converts .md files into .html and parses italic and bold for .md files
• v0.0.1 converts TIL post (.txt file) into .html file, specify output location, specify stylesheet url, view app version, view app help message

Installation

1. Download and install the latest version of python. Open a terminal and check that it is installed.

   Windows

   py --version
   

   Linux/MAC OS

   python3 --version
   

2. Make sure you have upgraded version of pip.

   Windows

   py -m pip install --upgrade pip
   

   Linux/MAC OS

   python3 -m pip install --upgrade pip
   

3. Install gogoweb using pip.

   Windows

   pip install gogoweb
   

   Linux/MAC OS

   python3 -m pip install gogoweb
   

4. Check that the package was installed

   pip show gogoweb
   

5. Check that you have the latest version of the app.

   Windows

   py -m gogoweb.convert -v
   

   Linux/MAC OS

   python3 -m gogoweb.convert -v
   

   If you get ModuleNotFoundError: No module named 'gogoweb':

   • Check the Location result from Step 4 to see which Python folder it installed to (Ex: Python311 is 3.11 and Python 312 is 3.12)
   • Specify the Python version it was installed to when running the Python commands:

   Windows

   py -3.12 -m gogoweb.convert -v
   

   Linux/MAC OS

   python3 -3.12 -m gogoweb.convert -v
   

   If this works, you probably have multiple versions of Python on your machine. Specify the Python version when running commands.

Usage

View App Version

Windows

py -m gogoweb.convert --version
py -m gogoweb.convert -v

Linux/MAC OS

python3 -m gogoweb.convert -version
python3 -m gogoweb.convert -v

View Usage Message

Windows

py -m gogoweb.convert --help
py -m gogoweb.convert -h

Linux/MAC OS

python3 -m gogoweb.convert -help
python3 -m gogoweb.convert -h

Convert .txt to .html

Windows

py -m gogoweb.convert <file or folder path>

Linux/MAC OS

python3 -m gogoweb.convert <file or folder path>

Example 1 (Convert one file)

py -m gogoweb.convert ./examples/til_post1.txt

Example 2 (Convert a folder of files)

py -m gogoweb.convert ./examples

Output(s) can be found in current workding directory's til folder.

Specify Output Location

Windows

py -m gogoweb.convert <file or folder path> -o <folder path>

Linux/MAC OS

python3 -m gogoweb.convert <file or folder path> -o <folder path>

Example

py -m gogoweb.convert ./examples/examples.txt -o ./examples

Specify Stylesheet

Windows

py -m gogoweb.convert <file or folder path> -s <stylesheet url>

Linux/MAC OS

python3 -m gogoweb.convert <file or folder path> -s <stylesheet url>

Example

py -m gogoweb.convert ./examples/til_post2.txt -s https://cdnjs.cloudflare.com/ajax/libs/tufte-css/1.8.0/tufte.min.css

Specify Config File

Windows

py -m gogoweb.convert <file or folder path> -c <config toml file path>

Linux/MAC OS

python3 -m gogoweb.convert <file or folder path> -c <config toml file path>

Example

py -m gogoweb.convert ./examples -c src/gogoweb/config.toml

Additional Features Available for Markdown

Input file must be a .md file that is written in proper Markdown syntax

Front Matter Parsing

You may specify the following front matter in Markdown files and these will become the metadata of the resulting HTML file

Name	Type	Default	Description
description	string	undefined	The description of your document. Used for the page metadata and by search engines.
keywords	string[]	undefined	Keywords meta tag for the document page, for search engines.
lang	string	en	The language of your document.
title	string	file name	The text title of your document. Used for the page metadata.

How to specify front matter in a Markdown file:

---
title: Katie's Homepage
keywords: website, coding
description: This is Katie's personal website.
---

License

License (MIT)

See Examples Outputs

go-go-web examples

go-go-web's Issues

Add support for a horizontal rule in Markdown

When converting .md files to .html, add support for a horizontal rule in Markdown. The Markdown --- should get converted to an <hr> tag.

update test3.md test file to include front matter

update the test3.md test file to include front matter

test the following front matter:

• title
• lang
• description
• keywords

Update README to include any recent or future Markdown related features

• For any markdown specific features not specified in the README, add them to the Markdown section of the README
• For any future features for Markdown, add them but label them with "To be implemented"

Update gogoweb documentation website with more examples

Update go-go-web examples documentation site with examples of all features that are not presently displayed

Italics parsing in md files is not working

*text* and _text_ are not being parsed to <em>text</em>

Add heading to output HTML file based on title

If the file is a markdown file:

• look for the title in the front matter
• if front matter title is present, use it as the title and heading
• if not present, check if the first line in the content is following by 2 blank lines. If it is, use it as the title and heading.

If the file is a text file:

• check if the first line in the content is following by 2 blank lines. If it is, use it as the title and heading.

If a title/heading has been identified:

• In output HTML, use this to populate the <title>...</title> and add an <h1>...</h1> to the top of the <body>

Support author front matter in markdown

author in front matter will be parsed into html such as <meta name="author" content="John Doe">

Warning on output_file.write

parse frontmatter at the start of markdown_to_html() method

• in markdown_to_html() method, before doing anything, parse the file using python-frontmatter to separate the metadata (front matter) from markdown file contents (til post)
• only convert the markdown file contents to html

Supress delete/create of default output (til) folder if user specified custom output

If user specified a custom output location (via command line or via config file), do not delete/create the default til folder.

update the get_html_before_body() method to take metadata

Update the get_html_before_body() method which is used to generate html that appears before the body:

• add an additional parameter called metadata which includes all the metadata gotten from parsing using python-frontmatter
• instead of title param change it to filename
• set html lang to value of metadata if exists or 'en' by default
• set title to value of metadata if exists or filename by default
• if metadata object has 'keywords', add html meta tag for keywords
• if metadata object has 'description', add html meta tag for description

Update the calls of get_html_before_body() to reflect new params

• in text files there is no metadata (front matter) so pass {} as the param

break convert_to_html down to sub functions

@WangGithub0 Hi Yumei can I ask you to implement this fix since you added the Markdown feature?

Feedback from professor:
I would probably break the md and html aspects of this function into two smaller functions, and name this convert_txt or something:

def convert_to_html(text, type):
If type == ‘markdown':
return markdown_to_html(text)
else
return text_to_html(text)

That’s just pseudo code, but you get the idea.

update documentation for new front matter feature

• in README under Features, add the new front matter markdown feature
• in README under Installation, add pip install python-frontmatter
• in README, add a new section to explain the front matter items that can be specified in markdown files (currently title, keywords, description, lang). Also show how to write front matter in an .md file.
• update version of the app in _version.py

Add support for inline code blocks in Markdown

When converting .md files to .html, add support for inline code blocks. In Markdown, enclosing text in a single backtick causes the text to HTML to get rendered as <code>...text...</code>, and using 3-backticks creates fenced code block to get rendered in between <pre> tags.

update README

Please add Installation, Usage, License, Features in the README

add markdown files processing

add the process to parse italic and bold for Markdown file.

New Feature: Support -c and --config with Config File

Skip other types of files

When i input a folder path, could you use Warning for other types of files, and add file name?

missing explicitly specifying coding

Find front matter parser

Find front matter parser:

• in python
• MIT license
• able to parse Markdown file contents into two parts: front matter, and the rest of the Markdown file contents
• front matter is stored in key-value pairs (for example if stored in a dictionary-like object)
• read documentation to find out how to install and use

Create unit test for testing markdown_to_html function

Create a unit test for the following function src/convert.py def markdown_to_html(path, output_folder, css_url)

This function takes an input md file path and writes to a new .html file

Please create a temporary input file to test the following:

# Replace *italic* and _italic_ with <em>italic</em>
# Replace **bold** and __bold__ with <strong>bold</strong>
# Replace `text` with <code>text</code>
# Replace multi-line code blocks that are inside ```...``` with <pre>...</pre>

parameters of markdown_to_html:

path: the path to an input file (ex: "examples/test3.md")
(create a temporary file using: helpers.new_file(tmpdir, "your_file_name.md", pytest.your_global_var))

set pytest.your_global_var in conftest.py pytest_configure() to a long string which represents the markdown content of the input file (see other global variables in conftest.py to get an idea)

output_folder: the path for the output file (ex: til) (you can use a temporary directory, just put tmpdir)

css_url: no need to test this param, just use empty string

---

Create the unit test in tests/convert_test.py

To name the unit test, use def test_markdown_to_html(tmpdir, helpers):

How to compare the output of markdown_to_html after running the function:

    # Compare actual output file contents to expected
    output_path = tmpdir.join('your_file_name.html')
    assert helpers.file_contents(output_path) == pytest.your_html_global_var

you must set pytest.your_html_global_var in conftest.py pytest_configure() to a long string which represents the expected html content.

Please run pylint and autopep8 prior to submitting the pull request. (Instructions in contributing.md)

Delete til folder on each run

add delete and recreate til/ folder on each run?