All the new docs #41
All the new docs #41
Conversation
d0268a7 to
d10060e
Compare
| *If you are having troubles setting up jekyll, see https://jekyllrb.com/docs/installation/* | ||
|
|
||
| ### Serve the documentation | ||
| - `jekyll serve -s docs` |
There was a problem hiding this comment.
can you throw bundle exec in front of that
There was a problem hiding this comment.
Added a note under with that, since it's not required for everyone (just those not working on the default system ruby)
|
just did a content review and it's looking great 🎉 Added some comments to the google docs |
|
Instead of cluttering master with docs files, you could throw them into a branch called |
|
The idea with the docs folder is to be updatable with the code it documents at the same time. "Hey, you updated that section/stuff but the PR doesn't have any updated docs. What gives?" I found managing the two separate branches on Timber releases was pretty rough. |
| layout: default | ||
| --- | ||
|
|
||
| # Getting started |
There was a problem hiding this comment.
Similar to JS Buy SDK (& our github readme file), can we make this title "Slate" instead of getting started?
|
|
||
| # Getting started | ||
|
|
||
| Slate is a barebones starting point for developing Shopify themes in an efficient and performant way. It allows you to sync local files with your live shop, deploy to multiple environment at the same time, and organize stylesheets and scripts the way you want. |
There was a problem hiding this comment.
this should ideally be consistent with the opening paragraph of our github README. Not sure which one is better but, lets keep this consistent.
There was a problem hiding this comment.
How about:
Slate is a barebones starting point and command line tool for developing Shopify themes. It is designed to assist your development workflow and speed up the process of developing, testing, and deploying themes to Shopify stores.
It allows you to sync local files with your live shop, deploy to multiple environment at the same time, and organize stylesheets and scripts in a flexible way.
|
|
||
| Slate is a barebones starting point for developing Shopify themes in an efficient and performant way. It allows you to sync local files with your live shop, deploy to multiple environment at the same time, and organize stylesheets and scripts the way you want. | ||
|
|
||
| ## Setup your local environment |
|
|
||
| ## Setup your local environment | ||
|
|
||
| * Install Slate with `npm install @shopify/slate` |
There was a problem hiding this comment.
this section should likely be split out into:
Using NPM
Downloading from S3
There was a problem hiding this comment.
Wrote this before we decided on having the src files on S3 as well. Will update. @stevebosworth, what's the install path from S3? Download a zip, uncompress, navigate to it in terminal, then npm install?
There was a problem hiding this comment.
the install path is entirely through slate-cli now. You can download a .zip of the file through S3 that is just a built version of dist and does not contain any of the tools or a src folder.
slate-cli downloads a zipped version of our src folder and then builds the package.json for your new theme and runs npm install. Post release we discussed adding more customization options for builds from slate-cli
There was a problem hiding this comment.
The headings michael mentioned would be:
Using Slate-cli
and
Downloading from s3
| * Rename `config-sample.yml` to `config.yml` and add your [private app credentials](https://help.shopify.com/api/guides/api-credentials#generate-private-app-credentials) | ||
| * From within your new project folder in your command line, use the tasks below to build, sync, and watch your local files | ||
|
|
||
| > [Node](https://nodejs.org/en/) v6.2.1+ is required to fully benefit from Slate. If you want the template files without the build tools, get the latest zip here (TO DO: link). |
There was a problem hiding this comment.
6.2.1 is pretty specific.
IIRC, @macdonaldr93 had commented on our google doc that supporting older versions would be pretty simple w/Babel.
Does v4+ make sense?
|
|
||
| > [Node](https://nodejs.org/en/) v6.2.1+ is required to fully benefit from Slate. If you want the template files without the build tools, get the latest zip here (TO DO: link). | ||
|
|
||
| ## Slate commands |
There was a problem hiding this comment.
IMO, the content in this section presents better as a table, and should be consistent with the content on our github README.
| --- | ||
| layout: default | ||
| --- | ||
| # Tasks |
There was a problem hiding this comment.
consistency. I'm not sure why we're re-writing all these explanations, given that we already wrote them a few months back and had them 👀 at by the documentation team.
There was a problem hiding this comment.
Also: should this section be called "commands" since the focus here is on the Slate interface, and not the gulp implementation?
| --- | ||
| # Theme files | ||
|
|
||
| Slate is two separate parts. First, it's a barebones theme to develop your own styles and layouts on. Second, it's a toolkit of useful tasks to sync with your local files to your live store. [Learn more about the tasks here](/slate/tasks). |
There was a problem hiding this comment.
This seems like larger context to Slate, which should probably live in the "getting started" section - as the bit about tasks is not relevant to this section of content.
|
|
||
| All configuration files, layouts, and liquid templates required if you are submitting your theme to the Theme Store are included. See the [full guidelines for submission here](https://help.shopify.com/themes/development/theme-store-requirements?ref=slate-docs). | ||
|
|
||
| Standard liquid tags and logic that are likely to be used on a given template have been included with little to no markup, classes, or other code that you will need to strip out. |
There was a problem hiding this comment.
It's probably worth spending some extra time on this particular point and calling it out with a level 3 heading.
(ie. context around the "barebones" nature of our templates -- WARNING: THIS PAGE LOOKS BROKEN, BUT IT'S NOT.)
6da9b55 to
d83a61b
Compare
|
|
||
| ## Getting started | ||
|
|
||
| > [Node](https://nodejs.org/en/) v5.3+ is required to fully benefit from Slate. If you want the template files without the build tools, [get the latest zip here](http://sdks.shopifycdn.com/slate/latest/theme.zip). |
There was a problem hiding this comment.
https://github.com/nodejs/LTS#lts-schedule
AFAIK version 5 has no support schedule. Given version's 4 & 6 are currently in LTS, we should be targetting one of them for support (ideally 4 is supported, but 6+ is recommended).
|
|
||
| > [Node](https://nodejs.org/en/) v5.3+ is required to fully benefit from Slate. If you want the template files without the build tools, [get the latest zip here](http://sdks.shopifycdn.com/slate/latest/theme.zip). | ||
|
|
||
| 1. Install Slate with `npm install @shopify/slate --global` |
There was a problem hiding this comment.
npm install -g @shopify/slate is more common (and terse) syntax.
There was a problem hiding this comment.
Actually, it would also be good to mention the eaccesnote from here: https://github.com/Shopify/slate-cli#1-get-the-latest-version
Also just noticing that this set of instructions is very similar to, but divergent from the getting started instructions on the slate-cli readme.
Any reason for the discrepancy, or can we make these consistent?
| * `slate start` — Runs build, deploy, then watch to get you developing on your shop quickly | ||
| * `slate zip` — Builds and compresses your `dist` to a zip for easy manual upload | ||
|
|
||
| > Learn more about [all commands and descriptions](/slate/commands/) or how to [deploy to multiple environments](/slate/commands/#syncing-commands). |
There was a problem hiding this comment.
should be (/slate/commands/#sync-commands).
| slate deploy [--options] | ||
| ``` | ||
|
|
||
| ##### Options |
There was a problem hiding this comment.
looks like this title is in the wrong place (should be below the next couple of paragraphs if I'm reading this correctly?)
| layout: default | ||
| --- | ||
|
|
||
| # What's included |
There was a problem hiding this comment.
IMO this should be a simple page with the first paragraph and 2 links.
Templates and configuration should be a separate section, along with commands. Both should be linked to from here -- or perhaps each is a sub page of "What's included" and appear as a level 2 item in the nav.
There was a problem hiding this comment.
^ LMK if that doesn't make sense, I can explain it better if it's not clear what I mean...
There was a problem hiding this comment.
My thought of having all this (see image) on the same page is that it forces us to keep Slate minimal. If we see this page get longer, we know we're straying from our goals.
Thoughts @chrisberthe @stevebosworth @t-kelly @macdonaldr93
There was a problem hiding this comment.
I think I like it better as just the one pager. If we're going to add any complexity to slate, we'd be doing it through plugins and at that point we could have a new top level header "Plugins"
There was a problem hiding this comment.
I think the problem here (sorry if it wasn't clear above) is that "What's included" is Scaffold & CLI - but your "whats included" section gets right into the scaffold in the same section, right after calling out the following (leading to some weirdness in the docs heirarchy):
Slate is two separate parts. First, it’s a
barebones theme[theme scaffold] to develop your own styles and layouts on. Second, it’s a toolkit of useful commands to sync with your local files to your live store. Learn more about the commands here.
I'd suggest Templates & configuration / sections / sass / js & i11n are all part of a Theme Scaffold section, that lives at the same level as commands
There was a problem hiding this comment.
(I'd also suggest commands comes first in the list - as it's more terse and quicker to read through than the scaffold information).
There was a problem hiding this comment.
Gotcha, and agree with that explanation. Working on the update now
| - featured-product | ||
| ``` | ||
|
|
||
| ## Sass scaffolding and helpers |
There was a problem hiding this comment.
For consistency, should we be printing out the CSS directory structure here as well?
| - Responsive helpers to show/hide content and align text based on breakpoint names. [Example]({{ '/css-examples/#visibility-per-breakpoint' | prepend: site.baseurl }}) | ||
| - Prefixes. [Example]({{ '/css-examples/#' | prepend: site.baseurl }}) | ||
| - Visually hide or show content for screen reader accessibility. [Example]({{ '/css-examples/#visually-hide' | prepend: site.baseurl }}) | ||
|
|
There was a problem hiding this comment.
might be worth having a subsection on extending slate SCSS / Adding your own SCSS.
I mostly mention this because (although it might seem straightforward to us) Filippo mentioned having issues getting foundation scss to run in Slate during his testing.
|
|
||
| Performs a full deploy of your theme (see [slate deploy](#deploy)) and starts the watchers (see [slate watch](#watch)). | ||
|
|
||
| #### options |
There was a problem hiding this comment.
this should be a level 5 heading
|
|
||
| ## Slate Commands | ||
| A full list of possible Slate commands can be found [here](https://github.com/Shopify/slate-cli#overview). | ||
| It allows you to sync local files with your live shop, deploy to multiple environment at the same time, and organize stylesheets and scripts in a flexible way. |
There was a problem hiding this comment.
...multiple environments...
|
|
||
| Slate is a barebones starting point and command line tool for developing Shopify themes. It is designed to assist your development workflow and speed up the process of developing, testing, and deploying themes to Shopify stores. | ||
|
|
||
| It allows you to sync local files with your live shop, deploy to multiple environment at the same time, and organize stylesheets and scripts in a flexible way. |
There was a problem hiding this comment.
...multiple environments...
| ### Global | ||
| * `slate theme [name]` - Generate a theme with build tools | ||
| * `slate -h` - Options available in your current directory (differs if not in a theme) | ||
| * `slate -v` - See your current version of Slate and any dependencies |
There was a problem hiding this comment.
"See your current Slate version"?
There was a problem hiding this comment.
Good with "See your currently installed version of Slate and dependencies" ?
| * `slate deploy` — Builds your `dist` folder and replaces the theme set in config.yml | ||
| * `slate watch` — Listens for changes to your local source files and deploys them to your shop | ||
| * `slate start` — Runs build, deploy, then watch to get you developing on your shop quickly | ||
| * `slate zip` — Builds and compresses your `dist` to a zip for easy manual upload |
|
|
||
| # What's included | ||
|
|
||
| Slate is two separate parts. First, it's a barebones theme to develop your own styles and layouts on. Second, it's a toolkit of useful commands to sync with your local files to your live store. [Learn more about the commands here](/slate/commands). |
There was a problem hiding this comment.
...sync your local files to...
| sections/ | ||
| - collection-list | ||
| - featured-collection | ||
| - featured-product |
There was a problem hiding this comment.
👍. Were these selected based on how common these templates typically are? These have been in the top 5 added sections types since we released the theme editor so this is great.
There was a problem hiding this comment.
Yes exactly. They're basic enough to show off what sections can do, and likely going to be added to all themes (at least the ones we release). Biggest thing here is getting the JS working for both product.liquid and featured-product.liquid
| $breakpoint-has-widths: ($small, $medium-up); | ||
| ``` | ||
|
|
||
| Each column — or `.grid__item` — should be a direct child of a `.grid` container. Create the child element sizes with the format `breakpoint-name--one-tenth`. See the example below or look through `styles/global/grid.scss` for available sizes. |
There was a problem hiding this comment.
Should we specify to not mix grid/layout styling with content styling on the same element?
There was a problem hiding this comment.
Yea good call. Will add a quick note about that at the end of this sentence
|
|
||
| ## Responsive tables | ||
|
|
||
| For proper accessibility, tabular data should be build as table. Tables are notoriously difficult to build responsively, and while there are a lot of ways to do it, Slate includes a basic approach of adding the column labels as data attributes. Test the demo below in mobile mode to see it in action. |
There was a problem hiding this comment.
"...should be built as a table..."
|
|
||
| ### Visually hide | ||
|
|
||
| Sometimes it is necessary to visually hide content while keeping it accessible in the DOM. This is useful for hiding descriptive text for icons or form labels that you do not want shown. Screen readers, for example, do not read placeholder text on inputs as their label so need the `label` element. |
There was a problem hiding this comment.
"...their label so the label element is required."
| @@ -0,0 +1 @@ | |||
| console.log('slate.js'); | |||
|
|
||
| ## Getting started | ||
|
|
||
| > [Node](https://nodejs.org/en/) 4+ is supported, while 6+ is recommended to fully benefit from Slate. If you want the template files without the build tools, [get the latest zip here](http://sdks.shopifycdn.com/slate/latest/theme.zip). |
There was a problem hiding this comment.
update link to: https://sdks.shopifycdn.com/slate/latest/slate-src.zip
d85e738 to
2a04ccd
Compare
|
LGTM 🚀 |
|
🚢 |
| ## Slate commands | ||
|
|
||
| ### Global | ||
| * `slate theme [name]` - Generate a theme with build tools |
There was a problem hiding this comment.
mentioning build tools seems confusing. "Generate a new blank theme" is a little more straight
| slate theme [name] | ||
| ``` | ||
|
|
||
| Generate a theme with build tools. The name argument is required and you will be prompted to enter it if it's not provided. |
There was a problem hiding this comment.
mentioning build tools is a little confusing. "Generate a new blank theme. The name argument is required for the new theme directory."
|
This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
What up new docs! See doc content in this Google Doc since this PR would be too difficult to review.
Taking reference from js-buy-sdk docs (live version), I've setup a clean Jekyll version of Slate's documentation.
If we merge this PR, docs will go live even if the repo is private.
To do:
Not included, but cool potential future editions:
@Shopify/themes-fed