search

mayamcdougall / freelancer-pico

A Pico port of Freelancer by Start Bootstrap.
MIT License
11 stars 7 forks source link

readme

Freelancer Theme for Pico

This Theme is a port of the wonderful Freelancer Theme from Start Bootstrap, optimized for PicoCMS.

Freelancer is a one page, freelancer portfolio theme built with Bootstrap created by Start Bootstrap. This theme features several content sections, a responsive portfolio grid, modal windows for each portfolio item, and a contact form.

A Live Demo of the original theme is available from Start Bootstrap themselves.

Getting Started

To use this theme:

  1. Download the Latest Release on GitHub (or clone the repo directly into your Pico themes folder).
  2. Extract all files to themes/freelancer-pico folder within your Pico installation.
  3. Set your theme to freelancer-pico in Pico's config.yml.
  4. Configure your website using index.md and the YAML options described in Index Configuration below.
    • There's an optional starter template you can use if you want. Simply copy index-sample.md to your content folder and rename it index.md. It comes with every possible config option, with the proper YAML indentation, but starts commented out.
    • Simply uncomment (remove the #) the lines you need and their respective parents.
  5. Add items to your portfolio by adding .md files. Portfolio items have a few configuration options, so see Page Configuration below for more details.

Configuration Details

Freelancer for Pico builds you a one-page site with a portfolio gallery made from your markdown .md pages.

Your pages will each show up as a thumbnail tile in the portfolio section, and they'll showcase their content in a modal popup dialog.

Configuration of Freelancer is done entirely through the YAML metadata of your index.md. This metadata also contains all the content for the main page besides the portfolio items.

Please note that the content of your index.md (that is to say, the part after the YAML metadata) isn't actually used for anything in this theme, so if you write something there, you won't see it displayed anywhere.

We'll go into more details about the many configuration options below.

Standalone Pages

This Pico port also adds limited support for having additional, standalone pages. Any Pico page can be visited (gallery items included) and will be rendered as the full page instead of the usual Heading, Portfolio, About, and Contact sections. These pages won't be exposed as links anywhere however, you'll have to link to them yourself. They are mostly intended for semi-hidden pages, such as linking to a more in-depth page about one of your portfolio items. You can use them however you see fit. And if you add hidden: true to your page, it'll also be hidden from the gallery.

Page Order

Pico has several choices when it comes to ordering your pages (alphabetically, by date, or using a page meta property). With Freelancer, page order is used to determine the order of your portfolio items. You can change it in Pico's config.yml by changing the pages_order_by property.

# Example of Alphabetical order:
pages_order_by: alpha
pages_order: asc

Optionally, if you'd like your portfolio items to instead display in a specific, static order, you can set pages_order_by to meta, change pages_order_by_meta to index, and then give each page an index value in its metadata (eg index: 0, index: 1 and so on). You'll probably also want to set your pages_order to ascending (asc) if it's not already.

# Example of a Static order, using an `index` metadata value
pages_order_by_meta: index
pages_order_by: meta
pages_order: asc

Index Configuration

The bulk of Freelancer's configuration is done through your index.md, through a series of nested sections.

Indentation is important in your YAML header, so make sure each item is nested properly! They should also be in lower case.

Most items are optional and have default values.

There's an index-sample.md template available for you to copy if you'd like the indentation taken care of for you. Just be sure that your editor doesn't try to mess up the indentation when you uncomment each line.

Root Section

The following items are root-level, don't need to be indented, and don't have subsections.

# Example with multiple files.
css:
  - "%assets_url%/styles1.css"
  - "%assets_url%/styles2.css"
# Example with multiple files.
fonts:
  - https://fonts.googleapis.com/css?family=Roboto
  - https://fonts.googleapis.com/css?family=Ubuntu

header Section

The header section contains configuration related to Freelancer's masthead (the big header at the top of the page containing your avatar).

# Example Header Section
header:
  avatar: "%assets_url%/avatar.png"
  divider: pen
  skills: Writer, Blogger, Journalist.

nav Section

The nav section contains configuration related to the navigation bar.

# Example Nav Section
nav:
  portfolio: Projects
  about: About
  contact: Contact Us

portfolio:

The portfolio section contains configuration related to the portfolio gallery.

# Example Portfolio Section
portfolio:
  title: Recent Projects
  divider: clock
  disable_close_buttons: true

about Section

The about section contains configuration related to the about section of the page, no surprise there. This section contains a few blocks worth of text, with optional button "actions" at the bottom.

# Example Config
about:
  title: About Me
  divider: question
  content: |
    According to the earlier example, I suppose I'm a writer, blogger and journalist.
    You should check out my work, because I'm very important and successful.

contact Section

The contact section lets you configure and display your contact information, either as buttons or an email form.

Please note that having the contact form send email requires additional setup which is unfortunately out-of-scope of this theme. Sending email is a complicated process with security implications and should only be attempted if you're well versed in the subject. Please also check out the Contact Form Disclaimer below.

# Example of a contact section using a contact form.
contact:
  title: Get in Touch
  divider: envelope
  form:
    enabled: true
    action: "%assets_url%/email.php"
    method: POST
# Example of a contact section using icons
contact:
  items:
  - title: Twitter
    icon: twitter
    brands: true
    content: "@my_name_1234"
    link: https://twitter.com/my_name_1234
  - title: Email
    icon: envelope
    content: name@example.com
    link: mailto:name@example.com

location Section

The location section is located at the far left of the footer. It can hold a small blurb such as an address.

# Example Location Section
location:
  title: Address
  content: |
    123 Example Ave
    Someplace, CA, 01234

social Section

The social section is located in the middle of the footer. It can generate several social icon buttons with links.

# Example Social Section
social:
  title: Find Me On
  items:
  - icon: github
    brands: true
    link: https://github.com/octocat
  - icon: twitter
    brands: true
    link: https://twitter.com/my_name_1234
  - icon: envelope
    link: mailto:me@example.com

footer Section

The footer section is the "About" section located on the far right of the footer. It can hold a small blurb of text.

# Example Footer Section
footer:
  title:
  content: |
     Writer, Blogger, Journalist.
     Very Important Person.
     Super Skillful.

copyright Section

The copyright section is the copyright block located at the very bottom of the page.

# Example Single-Line Copyright
copyright: 
  content: Copyright © Myself 2021
# Example Multi-Line Copyright
copyright: 
  content: |
    Copyright © Myself 2021.
    All Rights Reserved.
    And some other legal print.

Page Configuration

Portfolio items and standalone pages share the same configuration options (since they're technically one in the same). Standalone pages (that are hidden from the gallery) don't require images, but you can include one if you'd like. It'll be displayed at the top just like in the modal view.

The content of your pages (below the YAML header) will be used for the main body of its modal view and/or page.

# Example Video
video: "%assets_url%/video.mp4"
# Example Video with MIME Type
video: ["%assets_url%/video.mp4", "video/mp4"]
# Example Video with Multiple Sources
video:
  - "%assets_url%/video.mp4"
  - "%assets_url%/video.mov"
# Example Thumbnail Video
thumbnail_video: "%assets_url%/thumbnail.mp4"
# Example Thumbnail Video with Multiple Sources
thumbnail_video:
  - "%assets_url%/thumbnail.mp4"
  - "%assets_url%/thumbnail.mov"
---
# Example Gallery Item / Standalone Page
Title: Awesome Thing
image: assets/images/awesome.png
Date: 2021/03/20
actions:
  - icon: external-link-alt
    content: Learn More
    link: http://example.com
---

Here's where I tell you about my super awesome thing!

Actions

The About section and standalone pages both support having button links at the bottom of their content. These "actions" are configured the same in either section, so I've condensed their descriptions here for simplicity.

Don't forget to apply the proper indentation no matter where you're using them!

# Example Actions
actions:
  - icon: download
    content: Free Download!
    link: "%assets_url%/download.zip"
  - icon: external-link-alt
    content: Learn More
    link: http://example.com
    disabled: true

Contact Form Disclaimer

The original Freelancer contact form used Proprietary Start Bootstrap javascript to tie into their paid contact-form service. This unfortunately meant that all the styles and theming around the contact form and its validation was essentially broken unless using their solution.

I've included a very basic script to allow users to instead utilize browser-based validation, as well as have a ajax-based form submission that way you can submit the form without leaving the page.

However, and I can't stress this enough, I am NOT a Javascript Developer! I don't know even a shred about Javascript, and this whole effort was done by following and tweaking a few tutorials.

The code works, in that, it doesn't throw any errors, and it successfully submits the form for post-processing. But I have absolutely no idea if it is secure or follows best coding practices in any way!

I felt that leaving the contact form "incomplete" just wasn't a good solution, so I did my best to bridge that gap.

If you are a Javascript Developer, and you see a flaw with this, or you think you can measurably improve it, please submit an Issue or a Pull Request with your suggestions. Thank you.

Color Customization

Since Freelancer is based on Bootstrap, there are a lot of built-in color variables that can be used for customization. By default in the original Freelancer code, these are configured using SCSS.

Since this port is only based on the final compiled version of Freelancer, most of these variables were unused and hard-coded to their compiled values.

As a workaround, I've gone through and find-and-replace'd most of them with their variable names for ease of customization using an additional CSS Stylesheet. This does mean that there could be a few instances of the wrong variable being used for the same color. If you find any instances where this is the case, please make a new Issue to let me know.

I've also added a few "Extra" CSS Variables for colors that were originally SCSS mixes of other colors. There's no way to accomplish mixing colors with regular CSS, so these extra variables can be used instead to manually replace said colors.

These... are a mess, and I apologize for that. I hate them too, but I haven't come up with a better solution that doesn't involve simply crushing all the color variations down to their primary color and pretending it's not different.

If you have any ideas for how to improve this while keeping faithful to the original source theme, feel free to open a new Issue with your suggestion.

Using Color Variables

The following color variables are available for use in your own CSS Stylesheet. There are also plenty more Bootstrap color variables available, however they go mostly unused out-of-the-box.

:root {
  /* Default Bootstrap Colors */
  --bs-primary: #1abc9c; /* Primary Color */
  --bs-primary-rgb: 26, 188, 156; /* Primary Color as RGB */
  --bs-secondary: #2c3e50; /* Secondary Color */
  --bs-secondary-rgb: 44, 62, 80; /* Secondary Color as RGB */

  /* Pico Additions */
  --bs-copyright: #1a252f; /* Darker Secondary Color used for Copyright background (Approx. RGB values times 0.6) */
  --bs-primary-dark: #16a085; /* Primary RGB * 0.85 */
  --bs-primary-darker: #15967d; /* Primary RGB * 0.80 */
  --bs-primary-darkest: #148d75; /* Primary RGB * 0.75 */
  --bs-primary-lighter-rgb: 60, 198, 171; /* Lighter, faded Primary Color used for the button Focus Highlight. */

  --bs-primary-lightest: #8ddece; /* Even lighter, faded Primary Color. Used as a Focus Highlight on the Contact Form */
  --bs-secondary-dark: #253544; /* Secondary RGB * 0.85 */
  --bs-secondary-darker: #233240; /*  Secondary RGB * 0.8 */
  --bs-secondary-darkest: #212f3c; /*  Secondary RGB * 0.75 */
  --bs-secondary-lighter-rgb: 76, 91, 106; /* Lighter, faded Secondary Color used for the button Focus Highlight. */
}

Using Original SCSS

Optionally, you may be able to generate new CSS using the original theme's SCSS, but this is out of the scope of this readme. There's also a small block of Pico additions at the end of styles.css you'll likely want to preserve if you do this.

Updating from 1.0

This 2.0 release is a complete rewrite from my older 1.0 port. The original 1.0 version was based on an out-of-date Jekyll port of Freelancer and not the upstream code.

The new 2.0 version should essentially be treated as a new theme.

While it shouldn't be too hard to "migrate" from the old version, just be mindful of the different header configuration values, since it's not intended to be a drop-in replacement.

Issues and Feature Requests

If you have any issues with this port, or would like to request a feature, please create a new Issue on GitHub.