Skript
Skript copied to clipboard
SkriptLang
🚀 Docs Site Improvements
Description
This PR aims to improve the docs site after last restyle #3935
Live Preview: https://ayhamal-ali.github.io/Skript/ (outdated since commit)
Changelog (Will be updated continuously) (currently up-to-date)
- 🟢 Added DarkMode (Switcher, AutoLoad from cookies)
- 🟢 Added sections page & supported EffectSection (added to both sections and effects page)
- 🟢 Added support for lower versions in search filter (v:2.5-)
- 🟢 Added Search results counter
- 🟢 Added support for branched version search (v:2.2-dev36)
- 🟢 Version number will now go to the GitHub changelog link of that version when clicked
- 🟢 Merged PR #4063
- 🟢 Added custom Skript SyntaxHighlighting (Much faster, made for Skript, Built-in)
- 🟢 Added stable version and more placeholders to be used later on
- 🟢 Anchor elements Improvements
- 🟢
Docstab is now clickable and will open a page with all the elements - 🟢 Added 'New' Tab (special case of docs tab) that show all the registered syntaxes with a version filter to see the new additions since specific version
- 🟢 Added new search filters (is:new type:cond type:expr etc.)
- 🟢 Added syntax type on the right side
- 🟢 Syntax left border will now depends on the type
- 🟢 Added copy search link to allow people to paste links with custom search parameter
- 🟢 Added 'new' badge beside new added/updated syntaxes
- 🟢 Allow generating hooks docs if in testing mode and doc-templates folders exists (to make it easier for debugging and new releases)
- 🟢 Added 'How to generate the docs' section to README
- 🟢 Added Javadocs
- 🟢 Made examples collapsible
- 🟢 Added a template for a yet-to-come docs feature (By Addon) cell which tells which addon created this element (this is still under progress so I left it commented to finish later)
- 🟢 Added a new header tab 'Dev Tools' for anything related to addon developement in general such as Javadocs and later on addon development tutorials maybe
- 🟢 Added
return typefor expressions and functions4 - 🟢 Searching will not look form matches in descriptions too
- 🟠 Improved the search bar placeholder text
- 🟠 Improved docs search by reading
[ ]asoff[ ]hand - 🟠 Improved page inital loading for chromium based browsers (up to 70%) by using content-visibility css property
- 🟠 Improved the overall style to be much easier to read and understand.
- 🟠 Shorten the tabs list by using sub-tabs
- 🟠 Code cleanup
- 🟠 Fixed all broken docs links in examples and descriptions
- 🟠 Improved the docs patterns to remove unnecessary parentheses such as [(script)] in ExprAllCommands
- 🟠 Unified the word "colour" to be "color" for better search results and unified usage
- 🟠 Update sections description & examples
- 🟠 Updated docs info of hooks (required-plugins section)
- 🟠 Fixed classes and events requiredPlugins section joining values using newline instead of ", "
- 🟠 Unified left-over "Colour" words in ExprColorOf
- 🟠 Search bar and search icon now have a tooltip to show some information
- 🟠 Dimmed the white text a bit in dark mode
- 🟠 Improve overall JS loading using 'defer'
- 🟠 Added theme-color meta tag
- 🟠 White theme improvements
- 🟠 Fix black theme flicker when on white theme on load
- 🟠 Improved Github API calls by using caches to avoid getting blocked by the API
- 🟠 Disabled effects keywords Syntax Highlighting (standardizing keywords a little)
- 🟠 Changed hash link from scrolling to search filter (Chrome wasn't scrolling properly)
Target Minecraft Versions: Any Requirements: None Related Issues:
- #1610
- #1436
- #4508
- #4609
- #4429
- #4718
Converting to draft since I am adding more features due to the recent updates
Add notes about teleport async changes to EffTeleport #4491
I just checked your PR (#4026) and yes, my bad 👍
When you scroll, the top element gets blocked by the category banner
Live site wasn't updated yet, give it another try now if you can 👍
It's fixed. When on mobile the example gets cut off for the last element
It's not until you click it that it fixes itself, and can then be collapsed
Couple of suggestions:
1.
I feel that everything is too big. The site looks good, but imagine browsing the docs on a small laptop screen (1366x768):
Only ~15 items on a list on the left, and only two item descriptions fit on a screen. So when scrolling you'll be almost always seeing only one whole item. I'd scale everything down by 20% or something. I know CSS so I can provide some proof of concept for my vision. Maybe we can have two styles that the user can choose, something like "comfortable" and "compact" in gmail:
I'm really more compact type of guy ;)
2.
Also, some less important things can be made smaller and less noticeable, like skript versions. How often does an average user need that information? Not much I think. So if it's not that important it can be smaller and give us more room for more important things:
Those who'll need it will find it, and for other it won't clutter the screen. And by the way, look at "usable in events" - that whole column should be wider, maybe dynamic, so it won't be too wide on smaller screens.
3.
Look at this:
It could be made so that on large screens the syntaxes would be in two or three columns:
Isn't that better?
4.
Nitpick: that button shouldn't change size after click. And some padding-right would be nice. But I'm thinking about something like this:
That way the button is small, but still very noticeable (because it's important). I got rid of some unneeded margins that were kinda breaking the flow of content. And I think that a bar like this is a common design pattern and that style kind fits here. That big chunk of color nicely separates the items. But I'm not entirely convinced so tell me what you think.
Also, that arrow could be easily animated to rotate, that'd be nice.
5.
Alternating row colors in tables don't always look right, see here:
"Since" has the same shade as the last pattern. We could somehow change the syntaxes part to be more visually separated from the rest of the table. I'll think about it later.
6.
When I'm looking for a way to implement some feature in Skript, I'm always constantly jumping between parts of the syntax - events, expressions, conditions... If I'd have to open some menu to go to e.g. events, it would be a bad UX. It's better to do something like:
Of course that's only a rough concept. That submenu with elements of the syntax would only show in docs.
Other
I think the search bar looks kinda weird, maybe it should be taller and have more padding. Also, the blue search icons really don't fit the black theme.
Maybe I'll write some CSS later and make some pull requests with various improvements.
Thanks for your efforts doing this,
- That might be nice to have, some option to switch between normal and compact
- With the current design, this wouldn't be nice from a designer prespective and equality of blocks - though usable in events isn't appealing atm indeed
Also,
sincesection can have long lines sometimes so a proper space shall be reserved - Could be nice to have though I am not satisfied enough by either looks - e.g. look at the empty slot at the end
- The arrow font size doesn't change that's just the arrow itself and how the character is designed, minor thing but could be improved 4.1. The design of example orange box is intended, the suggested design is too much distracting (currently following the rule of 30% - 70% color palette) 4.2. Minor suggestion but that could slow low end devices
- Pattern rows have its own css even/odd rule and other rows have their own too, I have some new design that will change all these so it's fine for now
- I don't much like the look of this though it could be implemented in another way on that it depends
As for this PR, it's has reached its end, another PR will be opened after this with new UI/UX improvements, will keep this comment in mind for the accepted suggestions
When searching through all the docs, EffectSections like EffSecSpawn show up twice (the Effect version and the Section version). Would it be possible to only show the Section version?
Possible but it's not a good idea to do, they are duplicated for a reason, we don't want to make exceptions and have an unexpected results later on, also it means there is an effect and there is an EffectSection for that element which will be benificial for users to know
On the types section (and probably all other sections), when I click on the last element, it actually highlights the one above it (I'm assuming this has to do with the scrollbar position)
Yep, that's fine as the 'sensor' only checks in the middle-top of the screen, the last element always gets missed but that's okay, if I increase the sensor range it will be more sensitive to scrolls and highlight elements earlier than they're in the middle of the screen
Also, the Spawn EffectSection is titled as a Section (instead of an EffectSection). I could've sworn it was different before but maybe not. Do you think it would be better to display it as one (I should add it is displayed as EffectSection in effects category) (see https://ayhamal-ali.github.io/Skript/sections.html?search=#EffSecSpawn)
Yep, in Effects page it says EffectSection while in Sections page it says Section, not sure if we should unify that? let me know
I think both should say EffectSection, and there should only be one. The term EffectSection implies it can both be used as an effect and a section, and the description states this too. I don't think it's good to have them duplicated in the docs.
I don't think we should standardize colour to be color. It should remain colour as Skript was made in Switzerland where they use colour based on the British English. The whole world uses colour accept American English.