modxorg / docsapp Goto Github PK
View Code? Open in Web Editor NEWSlim app to serve MODX documentation as markdown, with support for different versions and stuff. Also mirrored at docs.modx.org.
Home Page: https://docs.modx.com/
Slim app to serve MODX documentation as markdown, with support for different versions and stuff. Also mirrored at docs.modx.org.
Home Page: https://docs.modx.com/
The build workflow for styles (npm run build:css
) can no longer be executed on newer Macs because of node compatibility stuff.
This is not my expertise, but on other projects I've simply replaced node-sass
with sass
in the package.json, and changed the command to sass --style=compressed src/scss:dist
. When I try to do this for the docsapp however, it seems to be falling over on some of the magic in template/src/scss/_breakpoints.scss
which I'm not sure how to best rewrite.
@christianseel Any chance you could pitch in here and get the sass build workflow updated? JS workflow still works.
There are no styles for blockquote
https://docs.modx.org/current/en/building-sites/client-proofing/custom-manager-themes
https://docs.modx.com/current/ru/blablabla
Any missed resource inside RU doc section
it would be more informative to have a 404 page in your language (f.e. I work with RU doc and expect 404 RU page)
All doc pages
Next meta fields should be added, otherwise social sharing looks like incorrect, please find attached image:
<meta name="twitter:image">
<meta name="og:image">
Current logo can be used for value attribute. Otherwise social network will grab some custom non relevant image(example shows image from right Opencollective block).
The symbol used to detect which key has been pressed to use as query parameter in the live search is deprecated.
Navigate to search.js, line 34:
More in depth info can be found at Stack Overflow: https://stackoverflow.com/questions/35394937/keyboardevent-keycode-deprecated-what-does-this-mean-in-practice
Add copy function to clipboard for code sections.
For example: https://prismjs.com/plugins/copy-to-clipboard/
Add a button that copies the code block to the clipboard when clicked.
https://docs.modx.com All doc pages been indexed
Special character ¶ gets into Google reach snippet:
Maybe we can use a different anchor symbol or alternatively use an attribute recommended by Google itself for non-indexing? Here it is:
https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#data-nosnippet-attr
P.S. I also have more ideas on how to make search snippet "richer", but I will probably describe this in next request.
all pages for 2.x and 3.x.
Please find icons ZIP attached (I think we should discuss this, which icon would be perfect finally, take my creativity as a first approximation :) ) plus next code should be added to docs.modx.com <head>
section:
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
<link rel="apple-touch-icon" sizes="57x57" href="/apple-touch-icon-57x57.png" />
<link rel="apple-touch-icon" sizes="72x72" href="/apple-touch-icon-72x72.png" />
<link rel="apple-touch-icon" sizes="76x76" href="/apple-touch-icon-76x76.png" />
<link rel="apple-touch-icon" sizes="114x114" href="/apple-touch-icon-114x114.png" />
<link rel="apple-touch-icon" sizes="120x120" href="/apple-touch-icon-120x120.png" />
<link rel="apple-touch-icon" sizes="144x144" href="/apple-touch-icon-144x144.png" />
<link rel="apple-touch-icon" sizes="152x152" href="/apple-touch-icon-152x152.png" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon-180x180.png" />
Let MODX brand awareness slightly increase among Mac device users, plus we can remove unnecessary requests to the server.
https://docs.modx.com/stats/page-not-found
We have a lot such requests everyday:
Top 50 most common requests
Commonly occurring 404 requests. Cached for 12 hours.
/apple-touch-icon.png 40,910 requests - Last seen 2021-04-08 00:34 CDT
/apple-touch-icon-precomposed.png 40,382 requests - Last seen 2021-04-07 23:43 CDT
P.S. the text is not very visible on the logo, probably we need a white edging around or some kind of shadow
It's probably a tie between markdown rendering and menu generation (#13) as to what's the slowest, so markdown rendering to html should also be cached.
Also bonus points for a CLI utility to do it from a deployment.
E.g. php docs.php lint {path/to/file.md} {path/to/file2.md}
which will check the validity of the markdown, links, etc.
Add Auto Prefixer after compiling Scss
https://www.npmjs.com/package/autoprefixer
After compiling Scss into CSS, we must automatically add vendor prefixes. To create cross-browser CSS
NA
The sidebar navigation is looking sharp, but a bit cluttered as we have so much content.
I'm thinking that to improve it, we should:
Could also style it more like accordions, but I don't think that fits the current style all that well.
I could not find fastField package on the first try, it turned out to be at the tail of the list. Now we essentially have two lists one by one - the first starts with a capital letter, the second with a small one.
It is very convenient to quickly find a package by the first letter of the name in the left tree, case of the first letter does not matter as for me here.
Currently have the language related items below the page title (not on home), but would be useful to have a different/better/more prominent way of switching to the other languages.
Start was made in #47 but not finished.
When showing the TOC, we should make sure there is more than 1 item. I'd propose to hide when there's only 1 heading
Not helpful for such small pages
Example: https://cube.dev/docs/getting-started
For convenience, go to the documentation page on
NA
It would be great if the MODX documentation is also accessible for people with disabilities. We can do this by using ARIA attributes.
The viewport meta tag should not contain any maximum-scale=2.0, minimum-scale=1.0
for accessibility reasons.
Avoiding maximum-scale allows your site to meet users’ needs and provide a better experience.
sandbox
attribute for <iframe>
https://blog.dareboost.com/en/2015/07/securing-iframe-sandbox-attribute/
I used something like this recently to embed google maps and dont worry about cookies and stuff:
<iframe seamlesssandbox="allow-forms allow-popups allow-scripts allow-pointer-lock" allowfullscreen></iframe>
(by Joshua Lückers)
Viewing the docs page on mobile has a few issues
Open the website on any mobile or open it through the responsive view through inspect element.
.content__inner {
margin: 5rem 1rem 0 1rem;
}
position: relative;
padding-right: 1.25rem;
&:after {
content: url(../src/svg/externallink.svg);
position: absolute;
bottom: 0;
width: 14px;
height: 1em;
line-height: 1em;
margin-left: 5px;
}
Thanks!
npm braces
packages is included as a sub-dependency from livereload
and includes is minor security issue. Thats not part of the browser JS, so no big deal for now.
Once livereload updates the dependency version, we need to do that as well.
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Low │ Regular Expression Denial of Service │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package │ braces │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Patched in │ >=2.3.1 │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of │ livereload [dev] │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path │ livereload > chokidar > anymatch > micromatch > braces │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info │ https://npmjs.com/advisories/786 │
└───────────────┴──────────────────────────────────────────────────────────────┘
https://www.markdownguide.org/extended-syntax/#footnotes
Does docs.modx.com support footnotes? As for me it doesn't ((
I keep thinking about how best to refer to terms from glossary... Capitalizing "Snippets", "Chunks" and so on - it doesn't look cool, besides, it is not welcomed by the rules of writing MODX documentation .. but this is not the main thing. How to make a link to a term so that the user, having met him for the first time, could go and get acquainted. "See more" block and excessive use of links (for example, a new term will be encountered by the user several times in the article, should we make them clickable each time?) doesn't seem like a good idea. A footnote could help here. You can select a new term, and somewhere below (for example, under "See More") add a new section (something like "Glossary"), where you specify:
blablabla.. Snippet[1], also Chunk[2]
[1] "Snippet" (link to Glossary, or even some portion of text...optionally with link "read more")
[2] "Chunk" (link or text..)
Wondering how to do that better, enjoy :)
The menu in the Russian version does not include one line.
English:
https://docs.modx.org/current/en/index
Russian:
https://docs.modx.org/current/ru/index
My suggestion is to move the top menu to the left block.
And where previously there was a menu to locate the search, and the place where previously the search was planned to use under the links with the icons of GitHub, Twitter, Slack.
Add issue Templates for Bug and feature request
For example:
https://github.com/modxcms/revolution/tree/2.x/.github/ISSUE_TEMPLATE
The lovely <base>
tag strikes again - the php library that's generating the table of contents for the "On this page" section outputs only #foo
, making it relative to the base tag, and not the current page.
From a quick look, the ListRenderer does not appear to support passing in the proper relative URL to base it off, so that may need to be extended or switched to a different renderer (TwigRenderer
, for example).
Rename references to "edit this page" to "improve this page".
The term "improve" might encourage people more to get involved in improving the documentation instead of "edit".
https://docs.modx.com/current/en/extras/collections
Broken images
For best SEO we should add a canonical link into the head that always points to the current
version URL. Otherwise we have duplicated content between the different versions.
Just my 2 cents: I'd rename current
to latest
in the URL.
This is specific for all documentation pages.
In my opinion new documentation looks very sweeping .. and takes up more space than it could (in this I’m talking only about the desktop, but I think you can expand it - where necessary - for mobile view). Especially when it comes to tables and snippets with a lot of parameters .. it takes a long time to flip through and it tires.
Syllabus menu on the right takes an unacceptably large place, this could be used f.e. to expand the tables(it located correct under mobile look - under caption before main content). We can also reduce the column width for the default parameter value.
Smaller paddings, margins, line heights..everything can be helpful.
let me demonstrate my ideas with the following screenshots:
By the way the previous documentation was more compact.
A CLI utility like php docs.php needs_attention
should write a JSON file (or similar data structure) to a predefined location (perhaps needs_attention.json
in the root of the doc source) and contain both the page name/link and the note so a special meta page can be added that lists pages needing attention.
#6 is a proposal, but doesn't work as nicely as I'd like.
Algolia Doc Search was proposed, which is free and easy to integrate supposedly.
My main concerns are:
Being able of adding additional filters (e.g. section) could be a bonus.
Add opengraph meta data to the docs.
So social media can show better previews.
Something like:
<meta property="og:type" content="website">
<meta property="og:site_name" content="{'site_name'|config}">
<meta property="og:title" content="{$_modx->resource.pagetitle}">
<meta property="og:description" content="{$_modx->resource.description}">
<meta property="og:url" content="{'site_url'|config}">
<meta property="og:locale" content="ru_RU">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="{$_modx->resource.pagetitle}">
<meta name="twitter:description" content="{$_modx->resource.description}">
<meta name="twitter:url" content="{'site_url'|config}{$uri}">
<meta name="twitter:domain" content="statum-trade.ru">
<meta name="twitter:site" content="@">
<meta name="twitter:creator" content="@...">
(Provided by @Ibochkarev)
N/a.
Clicking the logo should go to the index of the current version/language.
Go to a subpage of a language in a different version, e.g. https://docs.modx.org/2.x/nl/aan-de-slag. Clicking the logo should send you to the context-sensitive homepage, so https://docs.modx.org/2.x/nl/index, but instead it goes to https://docs.modx.org/ which then defaults to current/en/index
.
As can be witnessed in the closed pull requests from Dependabot linked below, we're a little behind on a bunch of PHP dependencies. This includes major updates with breaking changes that require code changes.
Help with this would be appreciated.
Adding titles to links in markdown doesn't work.
add a link like
[@FILE](building-sites/elements/template-variables/bindings/file-binding "FILE Binding")
The title like its working here: Bindings isn't generated in the docs
Headings in the docs should be <a>
with a anchor link to current heading.
<h2 id="example-heading">
<a href="/3.x/en/getting-started#example-heading">
Example Heading
</a>
</h2>
Make it easy to share and links specific sections.
It would be great if modern markdown tags like admonitions can be added to the parser.
https://squidfunk.github.io/mkdocs-material/reference/admonitions/
Footer is not pressed to the bottom.
Consider making the search input autofocus on the homepage so we can use the search function immediately without additional interaction (tab/click)
I visit the homepage mostly to search for something. I now have to press tab or click in the input field when I want to search trough the documentation.
The search bar is collapsed on mobile but doesn't allow easy/intuitive searching.
The search button should expand and focus a larger search bar, and the new live search results should take up the whole screen with the "all results" link in view.
Any URL at docs.modx.org on small screen sizes.
Right now the system is looping over all pages at render time to build the navigation which is super I/O intensive, and also slow; that should be cached as it doesn't change until a deployment (which can wipe/prime the cache).
Bonus points for a CLI utility to warm up the cache after a deployment.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.