New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"clone-theme" command to help developers to get started with themes #798

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
4 participants
@TonnyORG

TonnyORG commented Aug 23, 2018

So I wanted to get started building some themes, but I figured out I've to build "a skeleton" by my own.

Well, later I came with the idea to "create a skeleton theme" (which will contain ALL the minimal files required, which are around 3 files and 2 folders) to build a Ghost theme. However, later I figured out that this command was to "pull my basic theme" and just decompress it into the local folder so anyone can get started with it.

Starting from there, I figured out I could improve the command a little bit to actually use ANY available theme as "base" for your own theme. This is how clone-theme was created, and its main purpose is to allow theme-developers to spin up a skeleton quickly to build their own theme from there.

This command has some "tweaks" implemented, like detect if you're inside the root of your ghost installation, or maybe inside the "content" or "content/themes" folder, if so then the ghost/content/themes is the place where this script is going to install the theme for you. For other scenarios, clone-theme is going to install the cloned theme whenever you run this command.

My goal is to build some basic re-usable base templates like a plain very minimalist (just 100% required files) theme, a bootstrap 4 based one and more.

The currently supported parameters are:

Your feedback is gold to me!

If you have any feedback on this please let me know, any sort of improvement I could make on this will help me to get involved with the Ghost community and improve the quality of the code I contribute to you guys.

To-Dos:

  • tests (once I get the feature approved by the core team I'll start working with the tests).
  • anything else?
@JohnONolan

This comment has been minimized.

Show comment
Hide comment
@JohnONolan

JohnONolan Aug 23, 2018

Member

We've talked about this a few times as an idea, and it's definitely something I'd love to see in Ghost-CLI :)

I would advocate for keeping it fairly minimal. Forking other themes as a base is a cool idea but I could also see it going wrong / causing issues. I think it's probably ok for that use-case to be more manual.

Statamic do a really good job of CLI based theme skeleton creation: https://www.youtube.com/watch?v=Uj5vvTUU3Sc

I seem to remember Laraval having a really nice starting point too (which makes sense, pretty sure please is a fork of artisan.)

Also Ember-CLI does a nice job of stubbing new projects with a command

Member

JohnONolan commented Aug 23, 2018

We've talked about this a few times as an idea, and it's definitely something I'd love to see in Ghost-CLI :)

I would advocate for keeping it fairly minimal. Forking other themes as a base is a cool idea but I could also see it going wrong / causing issues. I think it's probably ok for that use-case to be more manual.

Statamic do a really good job of CLI based theme skeleton creation: https://www.youtube.com/watch?v=Uj5vvTUU3Sc

I seem to remember Laraval having a really nice starting point too (which makes sense, pretty sure please is a fork of artisan.)

Also Ember-CLI does a nice job of stubbing new projects with a command

@kirrg001

This comment has been minimized.

Show comment
Hide comment
@kirrg001

kirrg001 Aug 23, 2018

Contributor

I like the idea of getting a skeleton theme 👍

I would advocate for keeping it fairly minimal. Forking other themes as a base is a cool idea but I could also see it going wrong / causing issues. I think it's probably ok for that use-case to be more manual.

Agree to that. You can upload a theme in the admin client, pretty easy. Not sure about downloading any theme via the CLI 🤔 Especially because you need to look up the github url, copy it, enter the name etc. Not sure about it yet.

clone-theme

IMO command name could be discussed. Of course, it depends what the command will do at the end :)


How big is a skeleton zip? 🤔 Are there any good examples of a skeleton theme?

If it's super small, which i guess so (?), I was wondering if we could just put the zip into the CLI as asset. Or into Ghost - for the beginning. Casper is 304kb, which is too big i find, but i guess we are not talking about using Casper as skeleton? Or are we?

Contributor

kirrg001 commented Aug 23, 2018

I like the idea of getting a skeleton theme 👍

I would advocate for keeping it fairly minimal. Forking other themes as a base is a cool idea but I could also see it going wrong / causing issues. I think it's probably ok for that use-case to be more manual.

Agree to that. You can upload a theme in the admin client, pretty easy. Not sure about downloading any theme via the CLI 🤔 Especially because you need to look up the github url, copy it, enter the name etc. Not sure about it yet.

clone-theme

IMO command name could be discussed. Of course, it depends what the command will do at the end :)


How big is a skeleton zip? 🤔 Are there any good examples of a skeleton theme?

If it's super small, which i guess so (?), I was wondering if we could just put the zip into the CLI as asset. Or into Ghost - for the beginning. Casper is 304kb, which is too big i find, but i guess we are not talking about using Casper as skeleton? Or are we?

@acburdine

This comment has been minimized.

Show comment
Hide comment
@acburdine

acburdine Aug 23, 2018

Member

This is actually something @ErisDS and I had discussed a while back - the idea we had was to create some sort of ghost generate command that would actually call a Yeoman generator (https://github.com/ErisDS/generator-ghost). So you would essentially do this:

ghost generate theme
? Name: my-theme-name

=> then you'd have a new theme :)

I'm more in favor of the generator approach for a couple of reasons:

  1. It allows us to not be locked-in to creating new commands every time we want to be able to generate a new thing, e.g. ghost generate storage-adapter, etc.
  2. Yeoman generators are literally built for this sort of thing, and adds the ability for templated generation (e.g. putting placeholders in the theme files as opposed to modifying the package.json after clone)
Member

acburdine commented Aug 23, 2018

This is actually something @ErisDS and I had discussed a while back - the idea we had was to create some sort of ghost generate command that would actually call a Yeoman generator (https://github.com/ErisDS/generator-ghost). So you would essentially do this:

ghost generate theme
? Name: my-theme-name

=> then you'd have a new theme :)

I'm more in favor of the generator approach for a couple of reasons:

  1. It allows us to not be locked-in to creating new commands every time we want to be able to generate a new thing, e.g. ghost generate storage-adapter, etc.
  2. Yeoman generators are literally built for this sort of thing, and adds the ability for templated generation (e.g. putting placeholders in the theme files as opposed to modifying the package.json after clone)
@TonnyORG

This comment has been minimized.

Show comment
Hide comment
@TonnyORG

TonnyORG Aug 23, 2018

This is great, awesome feedback!

I also liked the idea to keep it as simple as possible, but at the end not sure what is "minimal acceptable" as skeleton.

At the begining I was thinking about this:

Structure

| - assets
  | - css
    | - screen.css (empty)
  | - fonts
     | - .gitkeep
  | - images
     | - .gitkeep
  | - js
     | - .gitkeep
| - partials
   | - post-card.hbs
| - default.hbs
| - index.hbs
| - package.json
| - post.hbs

default.hbs

<!DOCTYPE html>
<html lang="{{lang}}">
<head>

    {{!-- Document Settings --}}
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />

    {{!-- Base Meta --}}
    <title>{{meta_title}}</title>
    <meta name="HandheldFriendly" content="True" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    {{!-- Styles'n'Scripts --}}
    <link rel="stylesheet" type="text/css" href="{{asset "css/screen.css"}}" />

    {{!-- This tag outputs SEO meta+structured data and other important settings --}}
    {{ghost_head}}

</head>
<body>
    {{{body}}}

    {{!-- Ghost outputs important scripts and data with this tag - it should always be the very last thing before the closing body tag --}}
    {{ghost_foot}}

</body>
</html>

index.hbs

<header>
    <h1>
        {{#if @blog.logo}}
            <img src="{{@blog.logo}}" alt="{{@blog.title}}" />
        {{else}}
            {{@blog.title}}
        {{/if}}
    </h1>
</header>

<main>
    {{#foreach posts}}
        {{!-- The tag below includes the markup for each post - partials/post-card.hbs --}}
        {{> "post-card"}}
    {{/foreach}}
</main>

partials/post-card.hbs

<article>
    {{#if feature_image}}
        <section>
            <a href="{{url}}">
                <img src="{{feature_image}}" alt="{{title}}" />
            </a>
        </section>
    {{/if}}

    <section>
        <header>
            <a href="{{url}}">
                <h2>{{title}}</h2>
            </a>
        </header>
    </section>

    <section>
        <p>{{excerpt words="33"}}</p>
    </section>

    <footer>
        <h4>Author:</h4>

        <ul>
        {{#foreach authors}}
            <li>{{name}}</li>
        {{/foreach}}
        </ul>

        <ul>
            <li>Reading Time: {{reading_time}}</li>
            {{#if primary_tag}}
                <li>Primary Tag: {{primary_tag.name}}</li>
            {{/if}}
        </ul>
        </footer>
</article>

^ that structure thinking of just covering the basic HTML schema and showing up the developer some of the capabilities to work with a theme.

@kirrg001 totally agree with the HUGE disadvantage of having to look for the .zip url, is not for everyone.

@acburdine I like the idea of using Yeoman as well, let me perform some research tonite to see what I can do.

Let's touch base on this so I can actually move forward and create something to start with, whatever you guys decide to go with: our own "HTML" hosted at ghost-cli, with or without yeoman, etc.

TonnyORG commented Aug 23, 2018

This is great, awesome feedback!

I also liked the idea to keep it as simple as possible, but at the end not sure what is "minimal acceptable" as skeleton.

At the begining I was thinking about this:

Structure

| - assets
  | - css
    | - screen.css (empty)
  | - fonts
     | - .gitkeep
  | - images
     | - .gitkeep
  | - js
     | - .gitkeep
| - partials
   | - post-card.hbs
| - default.hbs
| - index.hbs
| - package.json
| - post.hbs

default.hbs

<!DOCTYPE html>
<html lang="{{lang}}">
<head>

    {{!-- Document Settings --}}
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />

    {{!-- Base Meta --}}
    <title>{{meta_title}}</title>
    <meta name="HandheldFriendly" content="True" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    {{!-- Styles'n'Scripts --}}
    <link rel="stylesheet" type="text/css" href="{{asset "css/screen.css"}}" />

    {{!-- This tag outputs SEO meta+structured data and other important settings --}}
    {{ghost_head}}

</head>
<body>
    {{{body}}}

    {{!-- Ghost outputs important scripts and data with this tag - it should always be the very last thing before the closing body tag --}}
    {{ghost_foot}}

</body>
</html>

index.hbs

<header>
    <h1>
        {{#if @blog.logo}}
            <img src="{{@blog.logo}}" alt="{{@blog.title}}" />
        {{else}}
            {{@blog.title}}
        {{/if}}
    </h1>
</header>

<main>
    {{#foreach posts}}
        {{!-- The tag below includes the markup for each post - partials/post-card.hbs --}}
        {{> "post-card"}}
    {{/foreach}}
</main>

partials/post-card.hbs

<article>
    {{#if feature_image}}
        <section>
            <a href="{{url}}">
                <img src="{{feature_image}}" alt="{{title}}" />
            </a>
        </section>
    {{/if}}

    <section>
        <header>
            <a href="{{url}}">
                <h2>{{title}}</h2>
            </a>
        </header>
    </section>

    <section>
        <p>{{excerpt words="33"}}</p>
    </section>

    <footer>
        <h4>Author:</h4>

        <ul>
        {{#foreach authors}}
            <li>{{name}}</li>
        {{/foreach}}
        </ul>

        <ul>
            <li>Reading Time: {{reading_time}}</li>
            {{#if primary_tag}}
                <li>Primary Tag: {{primary_tag.name}}</li>
            {{/if}}
        </ul>
        </footer>
</article>

^ that structure thinking of just covering the basic HTML schema and showing up the developer some of the capabilities to work with a theme.

@kirrg001 totally agree with the HUGE disadvantage of having to look for the .zip url, is not for everyone.

@acburdine I like the idea of using Yeoman as well, let me perform some research tonite to see what I can do.

Let's touch base on this so I can actually move forward and create something to start with, whatever you guys decide to go with: our own "HTML" hosted at ghost-cli, with or without yeoman, etc.

@JohnONolan

This comment has been minimized.

Show comment
Hide comment
@JohnONolan

JohnONolan Aug 23, 2018

Member

Structure
I would suggest slight revision to structure

| - assets
  | - css
    | - screen.css *(boilerplate / css reset + styles needed for editor)*
  | - images
  | - js
| - default.hbs
| - index.hbs
| - post.hbs
| - page.hbs
| - tag.hbs
| - author.hbs
| - package.json

Default template suggestions look pretty good overall -- simplified version of casper files

Member

JohnONolan commented Aug 23, 2018

Structure
I would suggest slight revision to structure

| - assets
  | - css
    | - screen.css *(boilerplate / css reset + styles needed for editor)*
  | - images
  | - js
| - default.hbs
| - index.hbs
| - post.hbs
| - page.hbs
| - tag.hbs
| - author.hbs
| - package.json

Default template suggestions look pretty good overall -- simplified version of casper files

@TonnyORG

This comment has been minimized.

Show comment
Hide comment
@TonnyORG

TonnyORG Aug 24, 2018

I'm about to start working on this, but now the mandatory questions:

1.- Do we would like to use a CSS framework for this?
If so:

  • Bootstrap. Almost everyone in the current age is familiar with this
  • UI Kit. Fancy alternative
  • Skeleton. I liked it but is no-longer an active project
  • PureCSS. Never tried it, but is popular around
  • Other: ____________________

2.- Or maybe do we prefer to use an already built cross-compatible template?

  • Future Imperfect by HTML5Up. Personally, I like their templates even when I never used them.
  • Other: ____________________ I'm not getting used to use someone else's basic templates (in most cases I design my own) so feel free to share your input here as well.

3- Or do we wanna go with our own base? (Build a basic grid, image, text and responsive classes)

While I get some input on these responses, I'm going to work in the logic around the command to create the folder structure.

TonnyORG commented Aug 24, 2018

I'm about to start working on this, but now the mandatory questions:

1.- Do we would like to use a CSS framework for this?
If so:

  • Bootstrap. Almost everyone in the current age is familiar with this
  • UI Kit. Fancy alternative
  • Skeleton. I liked it but is no-longer an active project
  • PureCSS. Never tried it, but is popular around
  • Other: ____________________

2.- Or maybe do we prefer to use an already built cross-compatible template?

  • Future Imperfect by HTML5Up. Personally, I like their templates even when I never used them.
  • Other: ____________________ I'm not getting used to use someone else's basic templates (in most cases I design my own) so feel free to share your input here as well.

3- Or do we wanna go with our own base? (Build a basic grid, image, text and responsive classes)

While I get some input on these responses, I'm going to work in the logic around the command to create the folder structure.

@JohnONolan

This comment has been minimized.

Show comment
Hide comment
@JohnONolan

JohnONolan Aug 24, 2018

Member

None of the above tbh, if this is supposed to be a development starting point then it's better not to start with a lot of stuff which people then have to remove. The only thing worth including is probably the CSS rest found in Casper:

https://github.com/TryGhost/Casper/blob/master/assets/css/global.css#L19,L268

Member

JohnONolan commented Aug 24, 2018

None of the above tbh, if this is supposed to be a development starting point then it's better not to start with a lot of stuff which people then have to remove. The only thing worth including is probably the CSS rest found in Casper:

https://github.com/TryGhost/Casper/blob/master/assets/css/global.css#L19,L268

@TonnyORG

This comment has been minimized.

Show comment
Hide comment
@TonnyORG

TonnyORG Aug 25, 2018

Gotcha, that makes sense.

TonnyORG commented Aug 25, 2018

Gotcha, that makes sense.

@TonnyORG

This comment has been minimized.

Show comment
Hide comment
@TonnyORG

TonnyORG Aug 25, 2018

Per @acburdine recommendations, the first step was to create the new command to generate a skeleton theme (structured as @JohnONolan proposed) so here is it: TryGhost/generator-ghost#15

While I wait for @ErisDS's feedback on that PR, I'm going to build the logic in Ghost-Cli to use yeoman generators from ghost-cli, that way ghost-cli is just going to be a sort of "proxy" for the generator and we only need to maintain the generator itself 😃 giving the developers 2 options to create themes: through the ghost-cli or through yeoman generators (both will end with the same result).

TY everyone for your input, if you have any ideas to improve this, feel free to lmk.

TonnyORG commented Aug 25, 2018

Per @acburdine recommendations, the first step was to create the new command to generate a skeleton theme (structured as @JohnONolan proposed) so here is it: TryGhost/generator-ghost#15

While I wait for @ErisDS's feedback on that PR, I'm going to build the logic in Ghost-Cli to use yeoman generators from ghost-cli, that way ghost-cli is just going to be a sort of "proxy" for the generator and we only need to maintain the generator itself 😃 giving the developers 2 options to create themes: through the ghost-cli or through yeoman generators (both will end with the same result).

TY everyone for your input, if you have any ideas to improve this, feel free to lmk.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment