Poll: Create starter repos

[daviddarnes]

Summary

I've noticed that while Alembic can be used as a proper jekyll theme and as remote theme on the GitHub Pages platform, I'm still seeing people fork the repo and mod it accordingly. This isn't a problem, infact it's great to see people using the project to build their own sites and projects. Forking the repo is a good way to lock down the version updating and have all the files needed to modify to your own needs.

However I'd like to make it easier for people to setup their projects using Alembic as a theme and on on Jekyll-friendly platforms like Siteleaf, Netlify and more. If you'd like to give input on this concept then use one of these responses on this description:

• 👍 : I like this idea and would use it
• 👎 : I'm happy with the current state
• 🎉 : I like this, make a starter for my fave platform too
• 😄 : I like this, but just a single starter repo will do

[3CatMax]

😄 I've completely hit this issue with GitHub pages! I thought it was amazingly easy to use the GitHub remote theme gem to use the theme, but most of why I like the theme is because of all f the fancy bits and bobs that you have included. Examples of pages, buttons, navigation, images, etc. After figuring out the GitHub pages remote gem theme install and not seeing all the extra goodies, I ended up downloading the repo and getting it to work locally, then git pushing to my GitHub.io repository. Benefit: can run local because I now have all the relevant gems installed for that. Con: amount of frustration bumbling through it as a newb, and the likely unnecessary components that I now have on my GitHub.io. I would have found an extra set of instructions tacked on to the "As a GitHub Pages remote theme" tutorial super helpful, specifically including what contents need to be copied over for one to easily use/tweak all of the pre-made goodies that go are shown on the example page. Thanks for designing this, btw, I do like it or I never would have struggled to get it working with my woeful lack of knowledge on a Sunday ;p

[daviddarnes]

@3CatMax hey, thanks for using my theme! It's great that you got it all setup, but shame it wasn't as smooth as I'd hoped. So you were struggling to get the specific includes working? Or was it the gems that are setup as dependancies in the theme? We might be able to get this solved and not only will you have the theme hooked up right, but I can also update my documentation to help in these sorts of scenarios

[3CatMax]

Look to the even more basic than includes or dependancies ;p Following the GitHub instructions to install Jekyll was easy, but it doesn't give the user anything to build off of, not even a _posts folder. Installing the alembic theme gem works perfectly(as far as I can tell). The problem for the user that knows nothing about Jekyll (me) is that the theme "just" changes the colors and text of the demo page and does nothing else (add content folders/files), which I don't think it is created to do anyway.

For example, adding the basics of the website (boilerplate?):

• home page
• navigation bar
• categories page
• search bar
• hero image
• buttons
• social icons
• etc.

Since the GitHub pages custom theme didn't add all the actual content of folders and files (_posts, _includes, _layouts?, _sass?, assets, blog, and all the files in the home folder ;p) so that I could mess around with those instead of starting from scratch, that is when I realized I would need to add all of those files to get it to look the same as your example (https://alembic.darn.es/).

My problem is that I don't reeeaaaaallly understand all of the steps and regular practices using Jekyll and I am only familiar with pushing my website through Visual Studio's git tools ;p Which means I don't know which files I don't need when using the alembic remote theme gem (can list in .gitignore on my local copy and can delete on my GitHub.io directory). I'm pretty sure that I have everything working correctly on my GitHub.io site (maybe ;p Mostly still looks like your example as I am only slowly making changes at this point).

What would have helped me: Append to the "As a GitHub Pages remote theme" instructions:

• list of folders to add to the users own GitHub.io directory
• list of files in the home folder to add the users own GitHub.io directory

Past that, if I find any _includes or dependencies that don't work, I'll try to take notes and check back in ;p

[daviddarnes]

This makes sense now! Thanks for writing out that detailed reply. I'll be honest, I had a downloadable boilerplate at one point that included those very files you needed. However it became hard to manage in a single repo, which is probably what sparked this issue in the first place.

From what you've said on how you're using the theme that seems just fine, you'll miss out on theme updates but they happen a lot less now as I've got to what I think is a "feature complete" state. I'll definitely look into making a starter repo though. In the meantime it might be worth checking our my starter repo that deploys it to Netlify https://github.com/daviddarnes/alembic-netlify-cms It does come with some new learnings but you'll be in sync with the theme and you'll be able to use gems that GitHub Pages haven't whitelisted. Buuuuut from the way you're talking about your setup you seem to have it just the way you like it :)

[3CatMax]

I think my brain/sponge is already filled with all it can take with new learnings for the nonce ;p It might be worth it to add that link to the read.me file for this repo for any one else that doesn't know what they are doing and might decide to go with the cms approach instead. Thanks though!

[daviddarnes]

I wouldn't discredit yourself! You've done really well for someone who is new to all this!

[daviddarnes]

I made some starter kits if you want to try them out! https://alembic.darn.es/#quick-setup

[3CatMax]

I tried out your starter kit for the GitHub pages and think that is a step in the right direction. Still, the theme doesn't even show up yet, and I would argue that if a user wants to get up and running quickly with GitHub pages, they should go straight for the remote theme, which you can actually add right into your starter gem file and _config.yml file.

My opinion to make even gooder ;p

• [ ] Add gem "jekyll-remote-theme" to the Gemfile
• [ ] Add jekyll-remote-theme to the plugins list in _config.yml
• [ ] Add remote_theme: daviddarnes/alembic to the _config file
• [ ] Remove theme: alembic-jekyll-theme from the _config file
• [ ] change the readme file to add the configuration information only since it is for GitHub pages via the ZIP selection.

This gives immediate theme colors and nav bar instead of a white page with black text but as a boilerplate, adding more to flesh it out would be helpful.

Things that would make it fantastic for my use case:

• icon on top left
• right align nav menu
• the elements page (could be titled the about page with the side box and all the nifty social icon links)
• the hero image and text
• the button examples (I don't know what short codes are😅)

Thanks for picking this up again, btw!

[daviddarnes]

@3CatMax So are you saying the main Alembic theme repo should be changed to mainly use the remote theme mode? Alembic was designed to be a Jekyll theme gem first, GitHub Pages remote theme feature is a ring-fenced version of that. I'd prefer to keep it as a proper theme gem first, and provide the remote theme as an option.

I think you're right with the fleshing out though. Adding a generic logo would be useful for all of the starter kits. The nav should right align when a logo is present in the config. The feature image I will add to the some of the pages, but the elements page is a bit much as it's only meant to demo the shortcode (Jekyll includes). Would it help if the elements page on the theme site had them below each item?

[daviddarnes]

Closing this as I've made a couple of starter repos for people to get rolling with Alembic quicker https://alembic.darn.es/#quick-setup

[3CatMax]

This is so awesome, thanks for putting in the extra work!