Fields

• Institution
• Description
• Year started
• Year ended (optional)
• Current (optional)

Add notes to docs about config that another reserved word is made

Fields

• Role
• Company/Organization
• Month Started (optional)
• Month Ended (optional)
• Year Started (optional)
• Year ended (optional)
• Current (optional)

Requirements

• Add handler for image file extensions (make sure extension is lowercase):
  • jpg, jpeg
  • png (no exif)
  • webp
  • avix (no exif)
• Allow for exif data to be pulled and rendered
  • Add config option to disable
  • Document HTML classes of data
• Add to templates
  • Creative
  • Dimension
  • Ethereal
  • Greyscale
  • Lens
  • Paradigm Shift
  • Resume
  • Strata

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

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

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

• Minify images

• Minify CSS and JS

• 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

I Want to be able to have different types of blog posts that can be displayed in a custom way. i.e. recipies etc.

Requirements

• Be able to specify multiple types in the blog post section
• Be able to have separate styling for each type

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"

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

Fields

• Company
• Description
• Year started (optional)
• Month Started (optional)
• Year ended (optional)
• Month ended (optional)
• Current (optional)

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

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

Docs

• Readme
• CLI docs

Add notes to docs about config that another reserved word is made

• 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

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>)

Requirements

• Allow an entrypoint to add in your own custom filters in the generate_site() method
• Update the contributor docs filters section with details

• Aerial
• Creative
• Dimension
• Ethereal
• Freelancer
• Identity
• Read only
• Solid state
• Strata

Various pieces of information would be valuable to have in themes to make the usage less ambiguous. For example which content sections, which section fields etc. are allowed. There also needs to be 2 seperate specifications, the first is for themes in theme folders/remotes (theme configuration), and the second is for themes when they are copied into a directory using ezcv -c <theme> (instance configuration).

Requirements

• Create specification for information with set fields
  • Section fields (i.e. name, image, institution etc.)
• Create defaults for when no specification is provided
• Include required parameters in config file if init on theme
• Update main documentation with details about metadata file
  • The fact that it generates if one is not present
  • You can force regen from the command line
  • Specification for fields
  • What parameters are respected and which aren't
  • update to CLI documentation (in readme and CLI section)

Configurations

Example of dimension theme

name: dimension
ezcv_version: "0.3.0"
created: 2022-04-22
updated: 2022-04-22
folder: dimension # optional, only needed if folder is different than name field
sections: # optional (some themes have no sections)
  education:
    type: markdown
    fields: # Optional
      title: str
      institution:
        required: true
        type: str
      month_started: str
      year_started: str
      month_ended: str
      year_ended: str
      current: bool
  gallery:
    type: gallery
  projects:
    type: markdown
    fields:
      title:
        required: true
        type: str
      image: image
      link: str
  volunteering_experience:
    type: markdown
    fields:
      role:
        required: true
        type: str
      company:
        required: true
        type: str
      month_started: str
      year_started: str
      month_ended: str
      year_ended: str
      current: bool
  work_experience:
    type: markdown
    fields:
      role:
        required: true
        type: str
      company:
        required: true
        type: str
      month_started: str
      year_started: str
      month_ended: str
      year_ended: str
      current: bool

Formats

Datetime String

A regular string, but it must be in the format YYYY-MM-DD, so for April 21st 2022 it would be 2022-04-21

Literals

You can define literals to state strings that must be one of a set number of options, for example if a field only be the strings "literal1" or "literal2" you can use a list format to denote this:

field_name: 
  - literal1
  - literal2

So for example if you have the choice between the literals ["sophomore", "junior", "senior"] for the field level it would be:

level:
  - sophomore
  - junior
  - senior

Type indications

For fields within a section there is a type specifier to note the type for a field in the form of:

... # More stuff
sections:
    section_name:
        ...
       fields
            field_name: type
    section_name2:
       ...
       fields
            field_name: type
... # More stuff

So if there is a field called current in education section files it would look like

... # More stuff
sections:
    education:
        ...
       fields
            current: bool
... # More stuff

Type indicators are:

• bool: Boolean values (True or False)
• str: string values (plain text)
• dstring: datetime string (string in the format of YYYY-MM-DD)
• literal: literal (a set of strings see below for details)
• int: an integer (number)
• float: a floating point number (decimal number)

For literals you can use the following format

... # More stuff
sections:
    education:
        ... # More stuff
       fields
            level:
              - sophmore
              - junior
              - senior
... # More stuff

Required Fields

If a field is required you can denote it by adding a required: true key-value pair to the field, otherwise it is assumed to be optional. For example:

... # More stuff
sections:
    section_name:
       folder_name: str
       fields:
          field_name: 
            type: str
            required: true
    section_name2:
       folder_name: str
       fields:
          field_name: type
... # More stuff

Fields for instance configuration

• Theme Name: str
• Date Created: Datetime string
• Date Updated: Datetime string
• Acquisition Method: literal [source, first party, third party]
  • This indicates how the theme was gotten
    • Source = Included with ezcv (base, dimension)
    • First Party = From Qu-up/ezcv-themes
    • Third Party = Anywhere else
      • Would include URL or path where it was attained from
• Sections (see below)

Sections info

... # More stuff
sections:
    section_name:
       folder_name: str
       fields:
          field_name: 
            type: str
            required: true
    section_name2:
       folder_name: str
       fields:
          field_name: type
... # More stuff

Exceptions

Any exceptions to the above spec are noted below

Gallery

For the gallery since there is no additional fields only the folder_name key is necessary/usable

... # More stuff
sections:
    gallery: 
      folder_name: str
... # More stuff

Background

Having every theme included in the default installation is going to become a problem as the amount of themes increases. Instead allow them to be looked up and downloaded on first use from a remote source (github repo).

Requirements

• Come up with specification
• Add documentation

Additional steps

• Move built-in themes to own repo (probably in QU-UP

Fields (Univeral)

• Type (Book, website, Journal)

Fields (book)

• Author (First, Middle, Last)
• Translator (optional)
• Title
• ISBN (optional)
• URL (optional)
• Publisher info (name, city, state/province, year)
• DOI (Optional)

Fields (Website)

• URL
• Date accessed
• Date published
• Author

• Videos
  • Getting started video
  • Walkthrough each section and put it on usage
• Additional resources
  • Generating avatars
  • Free open source images
  • Online Vector graphics creation system
  • Online photo editor

Purpose

The specifics section of the documentation is used to explain in plain english to contributors how data flows through ezcv and how the system is constructed

Requirements

• Explain how an individual section is rendered
• Add diagrams for explaining how data flows through ezcv

Fields

• Name
• Birthday (optional)
• Email (optional)
• Call number (optional)
• Text number (optional)
• Job Title
• Company name
• Address (optional)
• Social Media's
• Include examples

Functionality

• init
  • Generates a new project with the proper layout
  • Select which template to use
    github pages (assumes repo is a github repo [check for .git folder])
• Preview
• Template

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

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

Docs

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

Fields

• Title
• image (optional)

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

TODO

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

ezcv theme [-l] [-c] [-s SECTION_NAME] [<theme>]

-s SECTION_NAME, --section SECTION_NAME The section name to initialize

Background

It would be nice to be able to specify remote repo's for downloading themes from. This is useful so that anyone who has multiple custom themes can specify a lookup natively.

implementation

• Allow theme field to also be the path to a url to a .zip file remotely
  • Look for file path if protocol is not specified
• Create new user-remotes.yml which is a seperate file specifically for new user remotes
  • Add an option to the CLI to add a new link to the user-remotes.yml file i.e. ezcv theme -r="filename.yml" or ezcv theme --remote="filename.yml" or

Documentation

• Document folder structure
• Document Config specification

Page Fields

• Created
• Updated
• Title (used for URL)
• Featured
• image
• Heading
• Tagline
• Content

TODO

• Create a custom parsing method for content sections called "blog"
• Create a theme schema that allows "overview", "single", and "feed" (overview with only 1 page) templates for each

Schemas

Below are the purposed schemas for the blog section.

Theme Schema

📁<theme_name>/
├── 📁css/
|   └──📄 <file_name>.css
├── 📁js/
|   └──📄 <file_name>.js
├── 📁images/
|   └──📄 <file_name>.<extension>
├── 📁sections/
|   └── 📁blog/
|            ├── 📄 overview.jinja
|            ├──📄 single.jinja
|            └── 📄 feed.jinja
|   └──📄 <section_name>.jinja
└── 📄index.jinja

Content Schema

├── 📁content/
│   ├── 📁blog/
│   |   └── 📝<filename>.md

Additional Steps

• Document creating content for blogs
• Document creating themes for blogs

Themes

• Dimension
• Grayscale
• solid_state
• read_only

Requirements

• Write initial HTML
• Write print stylesheet
• Add resume link to menu
• Integrate into themes
  • Base
  • Dimension
  • Remote themes

• Orange CV
• Greyscale
• Paradigm shift
• Lens

Requirements

• Allow for possible custom styling in some themes
• Add docs

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

• A standard ezcv project with the output folder being /site
• Routes.py with all the config for proxying /site
  • Option to run with continuous regeneration with a watchdog on contents folder
• A requirements.txt folder with everything you need to run the project
• 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

• 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

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

Files

• cli

  • init()
  • preview()
  • theme()
  • new_section()
  • optimize()
  • main()

• content

  • Image
  • Metadata
  • get_content_directories()
  • get_section_content()

• core

  • get_site_config()
  • _render_section()
  • _render_page()
  • _export()
  • generate_site()

• filters

  • inject_filters()
  • split_to_sublists()
  • get_image_path()
  • get_filename_without_extension()
  • pretty_datetime()
  • pretty_defaultdict()

• themes

  • get_theme_section_directories()
  • setup_remote_theme()
  • locate_theme_directory()
  • get_remote_themes()
  • get_theme_metadata()
  • _generate_fields()
  • generate_theme_metadata()
  • get_repo_last_updated()