siteleaf / learn.siteleaf.com Goto Github PK

These excerpts are all 👎

To a designer or novice front-end developer, the current "Getting started" page is extremely intimidating. Sawyer from 3 years ago would have looked at this and done a quick "NOPE". I think all of this content would make more sense in a "Local development" section.

In the "Getting Started" section, I think we can focus on the very basics, like explaining that Siteleaf theme files are just HTML and Liquid. And then offer links to more info on the various ways that you can add themes to Siteleaf:

• GitHub Sync (I would emphasis this as the preferred method)
• siteleaf push
• Upload through the Siteleaf UI

ref http://www.siteleaf.com/help/managing-your-site/user-roles/

http://learn.siteleaf.com should clearly mention that its for v2 and in "beta".

We should also link back to v1 help, in case a v1 person stumbles across this http://www.siteleaf.com/help/ (and/or move v1 help to a legacy section of Learn)

This doesn't really say "Siteleaf"...

(Not sure if you want this type of thing on here - feel free to move me elsewhere)

As a user first and coder second (or third or fourth), I'd appreciate a better explanation of when and why I might use collections instead of just throwing things into posts.

For a current project we're thinking of using Siteleaf for, I can't figure out which way to go and it feels like the wrong choice could mean a lot of work to fix. Or maybe I'm over-thinking it?

Selfish example: We're a podcast network and have Shows with episodes, hosts (who can be on multiple shows/episodes of shows), guests (who can be on multiple shows/episodes of shows), sponsors (who can be on multiple shows/episodes of shows) and are struggling with how best to organize everything.

We should include docs for people coming from v1

• http://www.siteleaf.com/help/v2/
• http://www.siteleaf.com/help/v2/improved-metadata-in-v2/
• http://www.siteleaf.com/help/v2/export-v1
• http://www.siteleaf.com/help/v2/gem

Similar to #22 this site could use an RSS feed, and we should teach people how to do it themselves.

e.g. https://github.com/snaptortoise/jekyll-rss-feeds

…need some love.

:wat:

Drag & drop works in the Siteleaf UI now, which will set the position front-matter for us.

In addition to #3, sprinkling code examples throughout the docs might be helpful.

For example, on the Meta Fields page, in addition to showing how the meta is outputted in the markdown, it would be helpful to see how you'd access that meta data in your template.

Right now its private so people can't submit issues/PRs

This is nitpicky, but now that we have a closer idea of the documentation structure, can we simplify some of the collection's permalinks:

• users-and-settings -> sites (this is the one that bugs me the most)
• siteleaf-v2 -> v2
• managing-content -> content
• theme-development -> themes

You'll want to do a find-and-replace to make sure any inline links are also updated.

😍

Mention something about the _sass/ directory, turning .scss and .sass files into CSS using frontmatter, etc.

I don't have a comprehensive list of tips, but maybe we can start compiling one:

• Exclude node_modules, bower_components, etc: http://stackoverflow.com/questions/26855552/jekyll-compiling-seems-way-too-slow?answertab=votes#tab-top

Inline code snippets are getting lost amongst the text. We may want to stylize these a bit to improve readability:

Currently:

Quick idea:

I like how the github docs show the current status:

One of the top questions I get asked is how to add default fields so they show up for all posts. Specifically because they want these fields to show up in the admin by default.

I usually point them to this: https://gist.github.com/sskylar/4a782de7c8d080cf5db6

And mention its okay for default keys to have blank values, and also to take advantage of Smart Field names (which is already mentioned).

This site could use one, also might be good for our help docs.

e.g. https://gist.github.com/sskylar/a96d145d476589aeeaa0

I'm noticing a lot of the documentation refers to files and directories, but these don't actually matter to Siteleaf.

It's an implementation detail of Jekyll, and I imagine will only confuse the less technical people or those not familiar with Jekyll.

We seem to get asked often about what Jekyll plugins we support. I'm actually not super clear on the answer to this...cc @larryfox @sskylar

By default, the landing page grid links go to the first file in collection.docs.first, which isn't necessarily in the order that we put.

Instead of .html

Can probably replace this page with a "Getting Help" document under the "Getting Started" section, explaining how to get support if you're on a paid plan (click the chat button at the bottom of your site in Siteleaf) and provide info on how to join the Slack for community support (provided to all plans)

Alongside #12, there should be more of an explanation of the different content types and what they do, as well as how to create/edit/delete them.

Additionally, add details about how clients don't need to worry about font, format, etc.

Let's dump the .html in links (soon before we start linking to thinks and have broken links)

We don't currently offer a permalink field by default

Would it be more useful to change "Settings" to "Configuration" and explain how to configure your site using the _config.yml file instead? We could do a brief explaination then link to Jekyll for more info:

• https://jekyllrb.com/docs/configuration/
• https://jekyllrb.com/docs/permalinks/

We also probably want to show an example of how you access any site metadata you add through the settings page: site.title, site.custom_metadata_key, etc

Just a minor typo on this page: learn.siteleaf.com/_getting-started/siteleaf-for-developers.markdown: "tech-saavy" should be "tech-savvy".

http://learn.siteleaf.com//sites/users/

Currently it says "Siteleaf Learn" for every page:

One thing that's a little odd right now is from the homepage, when you click on one of the top-level sections like "Managing Content", it takes you to "Managing Content" -> "Pages".

Not sure if this is the best solution, but we could instead take you to a "Managing Content" page that lists the subpages, kinda like a table of contents. A nice thing about this is we can link to a top-level page from within the Siteleaf Admin and let the user drill down to the topic they're interested in.

http://learn.siteleaf.com/managing-content/collections/

We should explain what output does and/or link to https://jekyllrb.com/docs/collections/#step-3-optionally-render-your-collections-documents-into-independent-files

cc https://github.com/oakstudios/Siteleaf/pull/1345

This is one big Siteleaf feature that we're not currently touching on. Might worth explaining how it works and how it can make local development easier.

cc #2

The sites endpoint now includes job info: https://github.com/oakstudios/Siteleaf/pull/1416

Unless we want to pay Swiftype $299/mo (I don't think we do), we'll need to switch over to Google CSE which has a JSON API we could use.

One thing that's really helpful when looking at documentation on MDN or WordPress is the "Related resources" at the bottom of each of their pages. I think it would be beneficial for us, when there's good related documentation, to link to it from the related page. For example, on our "Theme structure" page, it would be helpful to someone if we linked to Jekyll's "Directory structure" page.

Mention config that cannot be changed for GitHub Pages and Siteleaf: https://help.github.com/articles/configuring-jekyll/

This has been asked a couple times on Support/Slack...

• https://siteleaf.slack.com/archives/general/p1458155098000098
• https://siteleaf.slack.com/archives/general/p1458076274000070
• https://secure.helpscout.net/conversation/184224850/4210/?folderId=116630

If you really need custom plugins, you are welcome to compile the site on your own build server (running Jekyll + any custom code you want).

Here are the basic steps: (this could be expanded to be more helpful)

1. In your Siteleaf Hosting settings, choose GitHub Pages with format set to "Compile by GitHub Pages" (default setting). Your site will now publish as raw Jekyll files (.markdown instead of .html), and you can choose any branch you'd like (does not need to be gh-pages).
2. Create a webhook on github.com to alert your build server when this specific branch is updated.

That's it. Now clicking Publish in Siteleaf will trigger your build server which can compile your site and run any custom code you wish.

Note: Siteleaf's built-in Preview will exclude custom plugins, so you may see a slightly different output when using it.

This page is pretty unclear to me. I'm not sure what a lot of the content on this page means or when I'd use these attributes. Some code examples or further info would be helpful.

Manage > Settings screen shows a link to:

which directs to:

http://learn.siteleaf.com/managing-content/metadata/

but that page appears to have been moved here:

http://learn.siteleaf.com/content/metadata/

I dig this idea: https://oak.slack.com/archives/siteleaf/p1453221551000142

If you're trying to set up syncing/hosting with a repo in an organization, the organization's 3rd party restrictions need to be set to off.