Update README with theme content description #91
Conversation
|
looks good to me. then there is the general issue of how to actually find these files in case you want to copy/tweak them, but that is outside the scope of this particular issue. |
That is not specific to Minima. |
|
|
||
| ## Contents At-A-Glance |
There was a problem hiding this comment.
I wonder if we should put this after the "Customization" section https://github.com/ashmaroli/minima/blob/e00fa9508ffbf46f7c69626a5db8d13b495e34c1/README.md#customization
As a new user, I don't think I was concerned with the files and directories until I wanted to customize something specific.
There was a problem hiding this comment.
As a new user, I don't think I was concerned with the files and directories until I wanted to customize something specific.
That's true.. but I don't feel it's right to move it 'after' the Customization section.. Start with the basics, know what's what.. then proceed to customize..
|
|
||
| ## Contents At-A-Glance | ||
|
|
||
| Minima has been scaffolded by the `jekyll new-theme` command and therefore has all the necessary files and directories to have a new Jekyll site up and running with zero-configuration. |
There was a problem hiding this comment.
What about: "Minima is scaffolded by the jekyll new-theme command"
There was a problem hiding this comment.
Minima is scaffolded sounds like its continuously scaffolded.. like e.g. "The President is supported by his ministers.."
has been scaffolded makes it an event in the near past. e.g. "The Asset has been compromised.."
|
|
||
| Refers to files within the `_layouts` directory, these files define the markup for your theme. | ||
|
|
||
| - `default.html` — The base layout that lays the foundation for subsequent layouts. The derived layouts inject their contents into this file at the line that says ` {{ content }} ` and are linked to this file via FrontMatter declaration |
There was a problem hiding this comment.
Maybe we can link to the FrontMatter documentation the first time we use the term: https://jekyllrb.com/docs/frontmatter/
|
|
||
| ### Includes | ||
|
|
||
| Refers snippets of code within the `_includes` directory that can be inserted in multiple templates within the same theme-gem |
There was a problem hiding this comment.
What about using the "layout" vocabulary instead of introducing "templates":
"Refers snippets of code within the _includes directory that can be inserted in multiple layouts within the same theme-gem"
There was a problem hiding this comment.
includes can be inserted into another include as well..
| - `page.html` — The layout for your documents that contain FrontMatter, but are not posts. | ||
| - `post.html` — The layout for your posts. | ||
|
|
||
| ### Includes |
There was a problem hiding this comment.
Might not make sense logically but should we order "Includes" above "Layouts" to keep it alphabetical like you did for the directory contents?
|
|
||
| Refers snippets of code within the `_includes` directory that can be inserted in multiple templates within the same theme-gem | ||
|
|
||
| - `disqus_comments.html` — code to markup disqus comment box. |
There was a problem hiding this comment.
We should stick to capitalizing the first letter (and keeping the starting dash and ending with the periods). It's a nice format.
|
|
||
| Refers to `.scss` files within the `_sass` directory that define the theme's styles. | ||
|
|
||
| - `minima.scss` — the core file imported by the pre-processed `main.scss`. It defines the defaults for the theme and further imports sass partials to supplement itself. |
There was a problem hiding this comment.
"The core file imported by the preprocessed main.scss. This defines the variable defaults for the theme and further imports sass partials to supplement itself."
| ### Assets | ||
|
|
||
| Refers to various asset files within the `assets` directory. | ||
| Contains the `main.scss` that imports sass files from within the `_sass` directory. This `main.scss` is what gets processed into the theme's main stylesheet `main.css` called by `_layouts/default.html` via `_includes/head.html`. |
There was a problem hiding this comment.
Maybe we should stick to the bulleted list here in case more structural content shows up later on and just for consistency.
There was a problem hiding this comment.
leaving as is, because assets/ in Minima contains only one file. Future additions will have to update this section as required.
|
Thank you for your feedback @joeydong. Pushed a couple of changes. 😃 |
|
Requesting a review from @DirtyF and anyone in @jekyll/documentation. |
|
LGTM. @benbalter any thoughts? |
|
Wow. Thanks for this @ashmaroli. Especially for a theme targeted at new Jekyll users, this is extremely helpful to giving them a starting point to grow, not just a website. Nice work. @jellybot: merge +docs. |
Merge pull request 91
Add a section briefing on the various files within the theme-gem
Addresses #87