Giter VIP home page Giter VIP logo

docsapp's People

Contributors

bruno17 avatar camicase82 avatar christianseel avatar dependabot[bot] avatar guyinpv avatar ibochkarev avatar imgbotapp avatar joshualuckers avatar mark-h avatar optimuscrime avatar tonyklapatch avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar

Forkers

tonyklapatch optimuscrime alroniks guyinpv crazyboy49z joshualuckers christianseel gpsietzema lucyi theboxer davidpede ibochkarev ant-tar bruno17 trotalo

docsapp's Issues

Change the font size and line spacing for menu and text

Summary

Change the font size and line spacing to improve the presentation of information and increase the usable space.

Before editing:

font-size: 14px; line-height: 1rem;

Index | MODX Documentation 2019-04-11 09-38-13

After editing:
font-size: 12px; line-height: 1.5;

Index | MODX Documentation 2019-04-11 09-40-38

Update assets build workflow

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.

Image meta fields

Affected page(s)

All doc pages

What needs to be improved?

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).

(1) Facebook — Mozilla Firefox 2023-05-19 09 39 34
2023-06-02 16 25 50

Live search uses KeyboardEvent.keyCode which is deprecated

Summary

The symbol used to detect which key has been pressed to use as query parameter in the live search is deprecated.

Step to reproduce

  1. Navigate to search.js, line 34:

    DocsApp/public/template/src/js/components/search.js

    Line 34 in 5c59fc8

    switch(e.keyCode) {

  2. Read the MDN web docs about KeyboardEvent.keyCode

More info

More in depth info can be found at Stack Overflow: https://stackoverflow.com/questions/35394937/keyboardevent-keycode-deprecated-what-does-this-mean-in-practice

Special anchor character ¶ gets indexed

Affected page(s)

https://docs.modx.com All doc pages been indexed

Here is link to search result: https://www.google.com/search?newwindow=1&safe=active&hl=ru&source=hp&ei=NvBQYLn3ILKAjLsP5YmvgAc&iflsig=AINFCbYAAAAAYFD-Rle16EezplJUDSiiJU1SjXY3RGdb&q=modx+getting+started&oq=modx+getting+started&gs_lcp=Cgdnd3Mtd2l6EAMyAggAOggIABCxAxCDAToLCAAQsQMQxwEQowI6DggAELEDEIMBEMcBEKMCOgUILhCxAzoFCAAQsQM6CAguELEDEIMBOg4IABCxAxCDARDHARCvAToICAAQxwEQrwE6BggAEBYQHlDpEliSMWDNMmgBcAB4AIABjwGIAfMLkgEEMTcuM5gBAKABAaoBB2d3cy13aXqwAQA&sclient=gws-wiz&ved=0ahUKEwi56vCqsLXvAhUyAGMBHeXEC3AQ4dUDCAY&uact=5

What needs to be improved?

Special character ¶ gets into Google reach snippet:

2021-03-16 21 02 35
2021-03-16 20 52 15

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.

Relevant context

all pages for 2.x and 3.x.

Apple icons

Summary

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" />

Why?

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

iconified.zip

Cache markdown rendering

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.

Sidebar navigation tweaks

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:

  • Hide child pages by default, unless the parent is active, or when the child pages are toggled by an arrow/toggler indicator on the left of the parent.
  • Not make parent items bold. The toggler for child pages serves as indication that there are subpages
  • On page render, scroll/focus the sidebar on the active page (if any); especially necessary for really long menus like extras and system settings
  • Double check the active state. Right now it seems that the active blue color is on all parent/child links. Perhaps when we remove bold from the parent items, we can instead use bold for the active hierarchy? [This may need fixes in the application code to apply the right classes]

Could also style it more like accordions, but I don't think that fits the current style all that well.

How about case insensitive left tree sorting?

Summary

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.

2021-03-06 17 52 52

Why?

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.

Finish a language picker

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.

Always show current active page in left menu tree

Summary

When visiting a page, I have to scroll on the left menu and find current active item. To understand where you are now. Again and again :)

ezgif com-video-to-gif(2)

Why?

it would be great to see what active selected menu item is now (with opened subpages if any, this already works) e.g. centered on height:
2021-03-07 09 28 22

Add translation for IN THIS DOCUMENT

Regardless of the chosen language (RU, EN, NL) the line IN THIS DOCUMENT remains in English.

You need to make the IN THIS DOCUMENT header changeable depending on the selected language.

Example:
NL: IN DIT DOCUMENT
RU: IN THIS DOCUMENT

image

Responsive issues on the home page

Summary

Viewing the docs page on mobile has a few issues

Step to reproduce

Open the website on any mobile or open it through the responsive view through inspect element.

image

Issues found

  • MODX Logo section kicks Search almost off screen and even if you manage to reach it it won't work ( you can reach it in landscape mode ). Might be nice to move search inside the hamburger menu
  • MODX Docs headline prints over the menu. A possible fix on line 662 of http://docs.modx.org/template/src/scss/app.scss:
 .content__inner {
    margin: 5rem 1rem 0 1rem;
  }
  • The link svg icon seems to go all over the place. Possible fix on line 112:
    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!

Fix security warning for `braces`

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                             │
└───────────────┴──────────────────────────────────────────────────────────────┘

Markdown footnotes

Summary

https://www.markdownguide.org/extended-syntax/#footnotes
Does docs.modx.com support footnotes? As for me it doesn't ((

Why?

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]

Glossary (or mini glossary)

[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 :)

Table of contents are linking to the base tag instead of current page

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).

Improve this page instead of edit this page

Summary

Rename references to "edit this page" to "improve this page".

Why?

The term "improve" might encourage people more to get involved in improving the documentation instead of "edit".

Add canonical link

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.

Parameter tables, side paddings and other abundance of free space can be reduced

Affected page(s)

This is specific for all documentation pages.

What needs to be improved?

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:

2020-01-26 23 57 22
2020-01-26 23 57 02
2020-01-26 23 56 15
2020-01-26 23 55 42
2020-01-27 00 02 12

By the way the previous documentation was more compact.

Add CLI utility to index pages with a `note`/`suggest_delete` meta

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.

Add a good search

#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:

  • Limit to the selected doc source (unless user chooses otherwise)
  • Proper ordered results; e.g. searching for "output modifier" should bring up the output modifier page first
  • Indexed search; gotta be fast.

Being able of adding additional filters (e.g. section) could be a bonus.

Allow links to wrap

Links (especially to the modx api) can be extremely long. We need to allow them to wrap.

Image 2019-03-30 at 8 18 04 PM

You cannot collapse a navigation item if it is active

Do not know whether this can be called a bug. But you cannot collapse a navigation item if it is active (the link of this section is open in the browser).

When you try to collapse the entire section, the page reloads.

doc_tree

Add opengraph schemas to header

Feature request

Summary

Add opengraph meta data to the docs.

Why is it needed?

So social media can show better previews.

Suggested solution(s)

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)

Related issue(s)/PR(s)

N/a.

[€50 bounty] Updating PHP dependencies: Slim, dotenv, phpunit

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

Summary

Adding titles to links in markdown doesn't work.

Step to reproduce

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

Make headlines clickable

Summary

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>

Why?

Make it easy to share and links specific sections.

Make the search input autofocus on home

Summary

Consider making the search input autofocus on the homepage so we can use the search function immediately without additional interaction (tab/click)

Why?

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.

Search not mobile friendly

Summary

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.

Step to reproduce

Any URL at docs.modx.org on small screen sizes.

Cache the menu generation

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.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.