Extend theming guide with "files" section #252
Conversation
_guides/theme-creation.md
Outdated
| }, | ||
| ``` | ||
|
|
||
| After installing the theme, these files will be available under `/plugins/<your-theme>/<file-name>`. |
There was a problem hiding this comment.
This is not true unless I'm missing something.
/ in this nomenclature applies to the http request root, the path from that root is /packages/:package/:filename
Below in your example you actually give the proper path.
There was a problem hiding this comment.
The folder path as is on disc doesn't really matter for the reader, as they can't control it directly anyhow.
There was a problem hiding this comment.
True, I was bound to the web context, what do you think about
After installing the theme, these files will be available under the web folder /plugins/...
There was a problem hiding this comment.
Expect it's not.
TL forces a subfolder for your package, if you have a file array containing foo.gif the http path to is
/packages/<package name>/foo.gif
The reader only cares about that, not sure why you want to mention a plugins dir?
Where do you get that from?
There was a problem hiding this comment.
Oh it's packages not plugins, sorry, just a typo!
| @@ -34,6 +34,29 @@ This will create a `package.json` file that you must edit as such: | |||
|
|
|||
| Although it is not required, we strongly recommend you also fill in the `"homepage"`, `"repository"`, and `"bugs"` sections. | |||
|
|
|||
| Optionally, you can distribute other files along with the theme stylesheet as follows: | |||
There was a problem hiding this comment.
I think you should give it a header so that this is its own section.
Or shove it into a bullet point, not sure which makes more sense. I tend to favor the section as it's easy to tell apart from the minimum setup.
There was a problem hiding this comment.
I like the section idea!
_guides/theme-creation.md
Outdated
| ```css | ||
| @font-face { | ||
| font-family: "Alternative Font Name"; | ||
| src: url(/packages/thelounge-theme-your-theme/alternative-font.woff2) format("woff2"); |
There was a problem hiding this comment.
url(/packages/<package name>/alternative-font.woff2) maybe? The repeated "theme" in that path makes it rather hard to read
There was a problem hiding this comment.
What I considered is the general theme naming convention (maybe unwritten) that the themes always start with thelounge-theme- prefix. Other thing is to keep the example code free of template like parts, e.g. to be a valid CSS. (otherwise the font name, file name should also be templated - in my opinion it'd make the example awkward). What do you think?
There was a problem hiding this comment.
templates are fine, it shows the reader what to substitute.
We don't need to overdo it, the file part is obvious, especially if they read the full guide.
However you never actually show the package name (as you only show the TL section of package.json) so the reader has no clue where suddenly that thing is coming from.
I'd simply write it as I proposed above, being valid css isn't important as you are talking to a human, not a browser.
It just needs to look like it and it still does that.
There was a problem hiding this comment.
If you do insist on an example over a semi templated form, at least make it something sane, thelounge-theme-example, not -your-theme
-your-theme is basically the same as templating, just with much more noise and I certainly stumbled over it while reading the diff, had to backtrack and validate that we really are stuttering and that it wasn't me messing up the reading part.
There was a problem hiding this comment.
Totally makes sense, thanks!
|
Change line 51 and line 56 to something like what brunnre8 mentioned
That should do it. |
| src: url(/packages/<package name>/alternative-font.woff2) format("woff2"); | ||
| } | ||
| ``` | ||
|
|
There was a problem hiding this comment.
(Can't comment on the proper line, GH only let's me comment lines you edited apparently)
Move the
For a comprehensive example, refer to the [
package.jsonfile ofthelounge-theme-solarized](https://github.com/thelounge/thelounge-theme-solarized/blob/master/package.json
part back up to the main section, else it looks good. Thanks!
There was a problem hiding this comment.
Neat, looks good to me. Thanks for the effort and persistence.
@MaxLeiter heads up: this needs a squash merge if you are fine with it.
While I was making a theme, I had to debug and analyze the source code to discover the ability to distribute files in a theme. This PR is to make it straightforward for others. Feel free to rephrase or ask me to do the same (suggestions welcome, I'm not native).