• [ ] https://pypi.org/project/md-mermaid/
• [ ] Add in rendering on the frontend

Docs

Documentation about formatting

• https://mermaid-js.github.io/mermaid

Example(s)

sequenceDiagram
    participant content folder
    participant template
    participant output html
    content folder->>template: Content is taken and parsed by template
    template->>output html: template rendered by jinja into output html

pie title Wordpress market share
    "wordpress" : 62
    "Drupal" : 3
    "squarespace" : 3
    "shopify": 3
    "everything else": 28

Include an example repo that has a flask webserver setup that generates a site and then uses flask as a webserver that points to the ezcv output.

Needed files

• [x] A standard ezcv project with the output folder being /site
• [x] Routes.py with all the config for proxying /site
  • [x] Option to run with continuous regeneration with a watchdog on contents folder
• [x] A requirements.txt folder with everything you need to run the project
• [x] Readme explaning how to run the project and it's options

Cli

Add a flag to the init command to allow for a site to be generated with this config

Extra steps

• [x] Create a repo with the flask + ezcv setup so that people can use github templates to create a new repo instead of just the Cli

Documentation

• [x] Document the CLI init option
• [x] Document the new repo with the added flask option
• [x] Document a way for people to integrate this feature into "standard" ezcv projects

Goal

Speed up build time by keeping a cache of files and only updating ones that have been changed since last build.

Requirements

• [ ] Find a way to store the information about the last_updated time for files
• [ ] Hook into the initial file list system so that it is widdled down to only files that have been updated since last build
• [ ] Add build --clean flag to ignore the cache and rebuild all files

Suggested time-based implementation

import os
import time
import datetime

last_updated_time = os.path.getmtime("example-current.md")
ctime_last_updated = time.ctime(last_updated_time )
datetime_last_updated = datetime.datetime.strptime(ctime_last_updated , "%a %b %d %H:%M:%S %Y")

More robust implementation

Cache file

• A hash of every template file (since if someone changes a template any content that uses that template automatically needs to be re-rendered)
• A hash and the content of every user created content file ( To check if individual pieces of content users created has been changed)
• A hash of all the hashes of each piece of content in the folder (allows you to check an entire content folder for any changes in 1 step)

i.e.

{
    "templates":{
        "index.jinja":"<hash here>"
    },

    "content":{

        "folders":{

            "education":{
                "hash":"<hash here>",
                "files":{
                    "example.md":"<hash here>"
                }
            }

        }
    }

}

Processing cache file

1. If there is no cache file do all the rendering and then generate a new cache file
2. If a cache file exists:
   1. Check if any template files have been changed, and if they have re-render all the content that uses the template file, then update any of the stored hashes for that content in the cache file
   2. All the content for the site is categorized by folders (see the content folder layout here), so loop through each folder hash and:
      1. compare the hash of the entire folder contents with the stored hash and then if they differ go to step 3, if they are the same then go to next folder since nothing has been changed
   3. If the folder caches differ step into the folder and iterate file hashes to determine which files need to be re-rendered and re-render them, then update the cache file with the new content
3. Read the new/updated cache file and spit out all the output files

The focus for this release was adding features that were not finalized in time for the 0.3.0-0.3.2 releases, and cleaning up some bugs.

Features

• Added required_config section to theme metadata that's used:
  • on initialization to generate the config.yml file
  • on build to cancel the build if a required value is missing from config.yml
• Added section command (note ezcv theme -s <section name> will no longer work)
  • use ezcv section <section name> to get information
  • use ezcv section <section name> [<type>] to create a new section (note type is only required for any non-markdown sections i.e. blogs [can be "blog" or "b"] or galleries [can be "gallery" or "g"]). See cli documentation for full usage details
• Added deepsource integration
• Added issue template for creating new themes

Themes

• Added massively
• Added blog
• Added evie
• Added parallax

Bug Fixes

• Fixed bug with downloading aerial theme from remote
• Fixed bug where ezcv_version was generated incorrectly in the metadata
• Fixed a bug where a theme without a metadata.yml file would not load properly

name: evie URL: https://onepagelove.com/evie

TODO

• [x] Create theme
  • [x] Create index.jijna
  • [x] Add in CSS/JS
  • [x] Create sections
  • [x] Create metadata
    • [x] Add in required: true to fields that need it
    • [x] Add in required_config
• [x] Add documentation to docs/included-themes.md
• [x] Add to remotes.yml

Reasoning

Example

required_config:
  avatar:
    type: str
    default: "https://example.com"
    description: "This is a link to an avatar image"

This would mean when using the theme to init a project there will be the following parameters added to config.yml

... # Other code
avatar: "https://example.com" # This is a link to an avatar image
...

Requirements

• [x] Ability to specify required variable, if no type is specified str is assumed
• [x] implement functionality for other attributes
  • [x] Default
  • [x] Description
• [x] Implement sensible defaults for attributes (default and description)
• [x] Allow for description to not be required
• [x] allow for default to not be required
• [x] Check in ezcv.core.generate_site() before generating
• [x] Use in ezcv.cli.init() when generating config.yml
• [x] ignore name and theme
• [x] Add to existing themes
  • [x] Dimension
  • [x] Qu-UP ezcv themes

Docs

• [x] Guide for creating your own theme with this included
• [x] Adding a notice that this won't generate when using ezcv theme -m
• [x] Document behaviour when default or description is not provided
• [x] Document behaviour for default and description
  • [x] Default is used in site generation as the default value in config.yml
  • [x] Description is added as a comment after default
  • [x] ignores name and theme

Add new CLI command

ezcv section -n <SECTION_NAME> [-t=<type>]

Steps

1. Check if theme is in project folder, if not copy to the folder
2. Generate current metadata if file is not available
3. Copy current metadata info
4. Create new files
5. ~Insert new section information and resave metadata (including fields where available)~ (not possible)

Type specification

Options:

• m or markdown: generate standard markdown section
• b or blog: Generate a blog
  • Append an o (overview), s (single), f (feed) for which you want to generate or don't include any to generate all
  • check if type starts with a b, then strip literal "blog" and "b", then check for "o", "s", "f" for indications on blog sections
  • Set default "fields" to ["title", "created", "updated"]
• g or gallery: generate a gallery

TODO

• [x] Implement command for creating new sections
• [x] Update docstrings
• [x] Update command so section info prints if section already exists
  • [x] Update readme and CLI docs once completed

Docs

• [x] Readme
• [x] CLI docs

May 16th 2022

Minor fixes related to release

Bug Fixes

• Fixed broken previews on documentation site
• Included missing livereload dependency

Documentation improvements

• Added additional theme provider suggestions

May 16th 2022

The focus for this release is on adding blog support, QoL features and making ezcv a more well rounded static site builder. There will be a few items released in 0.3.1 that were meant for 0.3.0, but due to the need for python -m ezcv in order for github pipelines to work this release is going out now.

Features

• Blog posts
• Theme Metadata
• Adding an optimized mode for builds to increase site performance
• Added ability to create and use custom ad-hoc filters; pass a list of function objects (called extra_filters) to ezcv.generate_site()
• Added ability to directly invoke ezcv through python binary after installation python -m ezcv
• Added ability to specify a remote URl for config.yml theme variable
• Added continuous previewing to ezcv -p
• Added option to initialize with flask ezcv init -f
• Added python -m ezcv invocation
• Added logging to files so attached loggers can get details for troubleshooting (logging.info and logging.debug are recommended settings)

Themes

• Added ability to embed theme metadata
• Added blog section to existing themes
  • dimension
  • grayscale
  • solid_state
  • read_only

Bug Fixes

• Added missing highlightjs to all themes for code blocks
• Fixed bugs with preview loading in included themes docs

Documentation improvements

• Added sections documenting new features
• Rearranged included themes section to be alphabetical
• Added section outlining sequence diagram for site generation
• Added additional resources to help generating content
• Added notice thanking theme providers

Files

• [x] cli

  • [x] init()
  • [x] preview()
  • [x] theme()
  • [x] new_section()
  • [x] optimize()
  • [x] main()

• [x] content

  • [x] Image
  • [x] Metadata
  • [x] get_content_directories()
  • [x] get_section_content()

• [x] core

  • [x] get_site_config()
  • [x] _render_section()
  • [x] _render_page()
  • [x] _export()
  • [x] generate_site()

• [x] filters

  • [x] inject_filters()
  • [x] split_to_sublists()
  • [x] get_image_path()
  • [x] get_filename_without_extension()
  • [x] pretty_datetime()
  • [x] pretty_defaultdict()

• [x] themes

  • [x] get_theme_section_directories()
  • [x] setup_remote_theme()
  • [x] locate_theme_directory()
  • [x] get_remote_themes()
  • [x] get_theme_metadata()
  • [x] _generate_fields()
  • [x] generate_theme_metadata()
  • [x] get_repo_last_updated()

Be able to specify

ezcv buiild -o or ezcv build --optimize

Purpose

This feature allows an optimized build of the site to be done, which will be faster for people who come to your site, but will take longer to build initially.

requirements

• [x] Minify images

• [x] Minify CSS and JS

• [x] Minify HTML?

• [ ] Add blog support

• Add docs about feature generally and what it does

• Add docs mentioning this only works with themes following https://ezcv.readthedocs.io/en/latest/theme-development/#folder-layout

• Add note to https://ezcv.readthedocs.io/en/latest/theme-development/#folder-layout that this layout is required to use the optimized flag on builds

Test list

• [ ] CLI tests
  • [ ] init()
    • [ ] With name provided and not
    • [ ] With theme provided and not
    • [ ] without name and theme
    • [ ] with name and theme
    • [ ] with theme that doesn't exists
    • [ ] with theme that is remote
    • [ ] with theme that is local
    • [ ] with theme included
  • [ ] section()
  • [ ] theme()
• [ ] core tests
  • [ ] generate site with all defaults
  • [ ] Generate site with each specific keyword variable defined
  • [ ] check the content.get_content_directories() function explicitly
  • [ ] Make sure to test 1 of each section
  • [ ] Test with no sections
  • [ ] test with a section that has content but no template file
  • [ ] test with a section that has template file but no content
  • [ ] also test gallery sections with each extension (".jpg", ".png", ".jpeg", ".gif", ".svg", ".webp", ".apng", ".jfif", ".pjpeg", ".pjp") and nonexistant extensions
  • [ ] Also check exif data parsing
  • [ ] test resume generation
• [ ] Themes tests
  • [ ] That the projects exits when a required_config is not provided

Notes

• Core tests will also cover the Content types and adding filters
• Autoreload, and the main cli entrypoint cannot be tested
• testing just covers that the expected files/sections are produced not for their accuracy

Create a new getting started video and add it to readme as well as update it on the main docs

Trailer

• What is ezcv (might need to be seperate video)
  • ezcv is a static site generator with all the batteries included to get you up and running quickly for a personal site
  • Not meant to be used to build buisness sites
  • Comes with helpful features like resume generation, ability to create custom sections, included themes
  • demo build with a pre-built site (explain mkdown files/yml as basis for generation)
    • Think of a word file that becomes a webpage
  • Built in pipelines for deployment

Getting started

• demo build with a pre-built site (explain mkdown files/yml as basis for generation)
  • Think of a word file that becomes a webpage
• Built in pipelines for deployment
• What you need to use ezcv
  • YAML
  • Markdown
  • Recommended to have a github account
  • If running locally need python 3.8+ and pip
• Tell people to go to the videos for whichever one they want (this video only covers remote editing)
• Explanation of options to build
  • Remote editing
  • local editing (separate video but also in readme under <details>)
  • ezcv frontend (separate video but also in readme under <details>)

Purpose

Refactor the code base to use metadata in generation and simplify process for generating content.

Notes

• [ ] Publicly the only API's that are accessible are
  • [ ] ezcv.core.generate_site() & ezcv.core.get_site_config
  • [ ] ezcv.filters All functions in here, but importantly will need to support injecting custom filters (and document it)
  • [ ] ezcv.content

Major changes

• When collecting the information about files and their locations, make it easier to access that data one time instead of in 12 different formats. For example, with templates the environment should be passed around since it knows where all the templates' files are, instead of passing the theme name and implicitly finding it every time
• Should locate top-level files earlier, and make sure to include blog-type sections in those top-level files
• rewrite image management (filter and export)
• Move site state into an object that holds all file locations
• Tag rendering so that multiple blog-type sections can be used
• Have pages export to folders by section, and make the names url safe (i.e. "My & Post" in the blog section should be at /blog/my-post.html)

Goals

• [ ] Specify section templates that are available using metadata so export can be simplified (specific function to find pages based on metadata)
• [ ] When rendering the pages check if content is available and skip if it's not for a given section (make sure <section_name>_html is set to "" so templates can know if the html is available.
• [ ] Unify blog rendering to be less guess-n-check and also do the rendering of all pages all in one place
• [ ] Write specific way of handling images for galleries
• [ ] Handle standard image exporting

Fields

• [ ] Tags

Features

• [ ] Way to get summary data/taglines to use in feeds (filter with blog post passed in that returns a summary?)

• [ ] Tagline/subtitle option

• [ ] Image option

• [ ] Way to specify featured posts

• [ ] Structured data

• [ ] RSA feed

• [ ] Add tagging/tag-management system

• [ ] Add Auto-pagination? (Maybe a js library with page-data stored) or global variable

• [ ] Auto Search (Lunr.js)

• [ ] Look into tagging/tag-management, and figure out a way to integrate that into the "overview" section

Features

• [ ] Create function to call to check for updates
• [ ] Let people know when they use the ezcv build that they should upgrade if a new version is available
  • [ ] Can use endpoint https://api.github.com/repos/QU-UP/ezcv-themes/branches/main
  • [ ] See below for implementation
  • [ ] Can be checked against the metadata of the theme
• [ ] Put a little (upgrade available) tag when someone uses ezcv -l and upgrades are available for local themes

Get ezcv theme details

import requests
import datetime
response = requests.get('https://api.github.com/repos/QU-UP/ezcv-themes/branches/main')

# print response
print(response)

# print json content
print(response.json()["commit"]["commit"]["author"]["date"])

print(datetime.datetime.strptime(response.json()["commit"]["commit"]["author"]["date"], "%Y-%m- 
%dT%H:%M:%SZ").strftime("%Y-%m-%d")) # returns string of "Year-Month-Day"