Giter VIP home page Giter VIP logo

cleaver's Introduction

Cleaver

Current Version License Total Downloads

๐Ÿ”ฅ A blazing-fast static site generator that uses Laravel's Blade templating engine and leverages JSON or Markdown files for super-extensible content.

composer create-project aschmelyun/cleaver your-site-name

Deploy to Netlify

Requirements

  • PHP 7.3 or higher
  • Fairly recent versions of node + npm

Installation

After creating your project with Composer, cd inside your project's root directory and install node dependencies:

npm install

From there you can build the site using the included demo content, which outputs to a dist/ folder in your project root:

npm run dev

Modifying your assets

Cleaver uses SCSS for styling, and there's a basic skeleton structure set up in the resources/assets/sass directory. Tailwind is imported by default so you can jump right in to rapid development and prototyping.

There's a bootstrapped JavaScript file that imports lodash, jQuery, and Vue dependencies through npm to use with your project. That can be modified by editing the resources/assets/js/app.js file.

Building the site

To compile the SCSS/JS assets and build the static site files, you can run npm run dev from the root. Additionally, using npm run watch starts up a local node server that you can use to view your compiled project, and will watch the entire resources/ directory for changes to any assets, views, or content files.

If you would like to build your site without compiling the assets, run the php cleaver build command from the project root.

Commands and arguments

If you build the site by calling php cleaver build directly, here's a list of the current commands and accompanying arguments you can use:

  • php cleaver build {page} builds the current site, rendering your content in the resources/content directory and outputting HTML organized in a directory tree to /dist. You can choose to render a single page or just a specific path in your content by including a page argument. (e.g. php cleaver build posts/my-cool-post.md)

Publishing your site

Once you're ready to publish your site, simply run the command:

npm run production

Which will minify your assets and build the site again with the new versioned files.

You can then publish your entire project to a host of your choice as long as the web root is pointed to the /dist folder. Additionally, you're free to just publish the built files in the dist folder by themselves.

Roadmap

Cleaver is still very much in development, and while it's designed to remain as simple as possible there's a few features that could make for a better overall experience. Here's what's on the path ahead:

  • Ability to use folders in content directory
  • Add collection containing all content into each view
  • A better cli interface and style during site builds
  • Ability to add in and use HTML in JSON content files
  • More detailed build errors if something goes wrong
  • Create and import site scaffolds from the command line

Contact Info

Have an issue? Submit it here! Want to get in touch or recommend a feature? Feel free to reach out to me on Twitter for any other questions or comments.

License

The MIT License (MIT). See LICENSE.md for more details.

cleaver's People

Contributors

aschmelyun avatar dependabot[bot] avatar morpheus7cs avatar ryangjchandler avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

cleaver's Issues

Better error checking and validation of content

Ensure all appropriate test cases are met and exceptions gracefully handled. If required attributes are missing, let the user know through detailed yet concise error messages in the console output. Include validation on specific attributes if they need to fit a certain format.

Upgrade to Tailwind 2.x

Will need to also replace the current Mix version with the latest version, and swap out Sass for PostCSS.

Create scaffold for blog site

Create a simple cleaver-blog-starter template that contains a few test posts, and a basic centered text roll layout. Highlight the content, but create spaces to add featured images, meta information, author attributes, etc.

Reference imports

Thank you for making this awesome tool!

I can see in the release-notes that:
External JSON files can now be imported into content by storing them in a resources/data directory and then referencing their path in your content file's JSON (see hello-world.json for an example of this)

I see "imports": "/data/example.json", but how do I reference it in the view?

Refactor codebase and align with PHP 8+

The entire codebase leaves a lot to be desired and is honestly kind of a mess. It could stand to be refactored from the ground up, and would make a nice addition to the next major version (2.0).

Additionally, it should utilize PHP 8.0 or even 8.1 methods and as such will require the necessary version on release.

The `laravel-mix` dependency is missing from package.json

Describe the issue

Hi there,
There is no reference to laravel-mix on package.json and none of the scripts is working as they all are using mix.

To reproduce the bug

Run npm install and then run npm run dev

Environment details:
N/A

Screenshots
If applicable, add screenshots to give more details about the bug. This will greatly improve the ability to debug and troubleshoot the issue.

Additional info
If you have any other information that would be helpful to know about this, please write it here!

Ability to import JSON files into multiple different content files

Use case and scenario would be something like, a catalog site with multiple different products. Instead of copying/pasting different sections of products for each page and having to maintain those files, have one large JSON file of products that can be imported to each page under a variable name. Then using collections, filter off the ones desired on each page.

Related to #5

Update cli output

Format and organize the data coming out of the terminal to both look better and be more relevant to build information.

Current output looks something like:

+ /Users/andrew/sites/cleaver.test/resources/content/index.json built successfully.
+ /Users/andrew/sites/cleaver.test/resources/content/posts/test-post.json built successfully.
- /Users/andrew/sites/cleaver.test/resources/content/hello-error.json could not be rendered, skipping this page.
* 2 pages built in 31.51ms *

Updated might look something like:

+ hello-world.json rendered to /
+ test-post.json rendered to /posts/test-post
- hello-error.json missing path attribute, skipping

โ€ข Build Summary โ€ข
+ 2 pages built in 31.51ms
- 1 page could not be built

Additionally, should also ensure formatting is a bit more spaced out, leaving room for commands above/below. Take notes for how Laravel mix outputs compiled asset info.

Use tailwind-css-purge

By default in the build process, include tailwind-css-purge to remove unused classes from the built CSS. Should significantly reduce overall asset size.

localhost:3000

Hello,

I just tried a fresh install, but the website does not load.
localhost:3000 turns forever whereas the browsersync ui loads perfectly.

It did not tried to tweak anything, yet. It's out-of-the-box.
I cannot understand what I'm doing wrong.
Can you help, please ?

I'm using MacOS 10.15.5 and PHP 7.4

Build specific pages

As an additional command to the build sequence, give the ability to build only specific pages by providing either a content filepath/name (e.g. docs.json), or the path specified in the file (e.g. /docs).

Ability to generate site scaffolding

One of the largest features to be added to Cleaver so far, this would give users the ability to quickly scaffold a starter site with example content and assets. The flow would look something like this:

  • Install Cleaver from the command line via composer create-project aschmelyun/cleaver project-name
  • cd into the project directory
  • Run php cleaver make blog or php cleaver make docs
  • Edit and add to the newly-added resources/content and resources/views files
  • Build your site with php cleaver or npm run dev

How this should work in the background is fairly simple. The make command will take an argument after it, and determine if it is:

  1. Listed as a shortcode for an official Cleaver scaffold (e.g. blog, docs) that ties to a GitHub URL in the source
  2. A valid GitHub URL

If either of those is true, the application removes all files from inside the resources directory (or the directory itself), and replaces them with the contents of the cloned git repository, passed in or accessed via shortcodes. The git repositories should be organized and set up as an incredibly simple structure, laid out the same way that the resources directory is.

This allows for people to create their own Cleaver starter templates and let other developers use them without having to manually clone the git repository, download the content files, or open a PR for command-line additions.

Add in RSS feed

Include a package or functionality to automatically add RSS feed of all items to /feed. This should be stored as a setting and can be turned on or off with a boolean value.

Ability to use external URLs as JSON sources

Like with hard-coded data files included in the src directory, give the user the ability to pull in data from an external URL's source. Should fire the call off with zttp, headers for JSON data, and reject if it's not in the proper format instead of erroring out.

Ensure adequate accessibility across site templates

Using a combination of Lighthouse scores and the Accessibility Insights for Web extension, ensure accessibility standards on all pre-created templates and demo sites are met.

This includes proper semantics in HTML, color contrast, font size and placement, etc.

command.get is not a function

command.get('php cleaver build', (error, stdout, stderr) => {
^

TypeError: command.get is not a function

when running npm run watch and trying to save a file

Ability to auto-generate output path

Right now, the path attribute is required in all content files. Instead of throwing an error if that is missing, auto-generate the output based on the file structure in the resources/content directory.

For example:

  • resources/content/posts/test-post.json should automatically render out an HTML file to dist/posts/test-post/index.html if there's no path attribute available
  • If a path attribute is present, that acts as an override to the path/name of the content file

.env support

Add support for using .env files, with vlucas/phpdotenv

Scaffold for online catalog site

Create a simple cleaver-catalog-starter template that highlights Cleaver's ability to generate and build data-driven sites via JSON. An online catalog of various products with specific attributes (think mechanical keyboards, computer parts, auto accessories), would be perfect for example content used alongside this.

Add support for API-based content acquisition

e.g. ability to pull content down from headless, hosted CMS platforms like Contentful, Prismic, or even WordPress's REST API.

The goal is to be able to pull content down from those platforms, and then use it to build out pages in a predictable manner instead of using flat JSON files. This should boost the usability of Cleaver up significantly higher ๐Ÿš€

#49 will need to be implemented first, for storing things like access tokens to the above platforms.

Use parsedown-extra instead of the standard parsedown

Is there any reasons as to why Cleaver doesn't use parsedown-extra by default?

Rather than having ugly CSS where you're selecting the nth-type of an element on a page, it could be solved by adding the classes to the markdown file as such:

[Click Me](https://aschmelyun.com/){.btn}

Switching out the standard parsedown package for parsedown-extra doesn't seem to break anything out of the box, and all the tests pass as before.

Create scaffold for docs sites

Create a simple cleaver-docs-starter template that works similar to the current usecleaver.com/docs page. Ensure at least a few test pages of content are included, and potentially add some interactivity via Vue.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.