invertase / docs.page Goto Github PK

Currently we require code languages manually, which won't work for all projects. Somehow we need to find a way to support dynamic languages.

https://highlightjs.org/ might be an option, however we'd have to ensure that the parsing of the language is carried out on the server (right now, it's on the client).

Various things on v2 of docs.page:

• layout of error page needs tweaking slightly
• if the frontmatter is causing the issue, let the user know.
• reimplement the debug page maybe

I'm seeing the following error when trying to open docs.page

The api needs to be reviewed, and types need to be refactored and tidied. Additionally the remark plugin system isn't properly typed right now, and should be fixed

The table of contents should be wider, at the moment it's unnecessarily cutting off a lot of content.

A local preview mode, (probably) without the support for PR and branch previews, to improve writing dev experience writing docs

Do we use the bundler service?

just need to check for these files as well.

navigation feature may be broken

I have tried to get the top navigation feature to work. So far I have failed. The sidebar works well, but not the top header navigation.

• Tried it together with sidebar, having navigation before and after in the docs.jsonconfig. No navigation appears.
• Tried it alone, no header navigation appears.

Thus in neither case can I get the header navigation to show.

My use case for it was that I was trying to use a sidebar as my main nav of course, and to also put two links in the header navigation that would always be present there to two external places, just for convenience.

Reproduction docs repo:

Here is a test reproduction repo: https://github.com/rydmike/docs_page_test
and site: https://docs.page/rydmike/docs_page_test

Having docs.json config file:

{
    "name": "DocsPageTests",
    "favicon": "/images/favicon.png",
    "logo": "/images/logo.png",
    "logoDark": "/images/logo.png",
    "theme": "#0x29B6F6",
    "zoomImages": "true",
    "noindex": "false",
    "sidebar": [
        ["Welcome",
            [
                ["Intro","/"],
                ["More intro", "/more_intro"]
            ]
        ],
        ["Zoom image", "/another_page"]
    ],
    "navigation": [
        ["Intro","/"],
        ["More intro", "/more_intro"],
        ["Package", "https://pub.dev/packages/flex_color_scheme"],
        ["Playground", "https://rydmike.com/flexcolorscheme/themesplayground-v5"]
    ]
}

Known issue, admonitions broken in #23.

It is undefined and we're trying to read it. Should be an easy fix

Currently any project added to the repositories.txt file needs to have a paths field in the docs.json file. It might be more beneficial to try and recursively scan the repositories docs/ directory for any .md{x} files and automatically do this for users.

Using the GQL API, you can perform a directory query however this might get expensive if there is many sub-directories.

Styling could be improved and also some issues;

Back ticks are still output and showing:

vs GH:

Improve styling:

Currently it just makes the text bold, won't be able to distinguish it from other bold text; the GH markdown approach seems a lot better:

docs.page:

vs GH:

The same applies to inline code blocks with links, it's currently just bold + underline:

docs.page:

vs GH:

If I click on an item in the Table of Contents menu, it will "light up" 1 items before, until you scroll a little bit further.
It should be active directly after clicking on an item in the menu.

Example:
https://docs.page/invertase/react-native-google-ads
Click on for e.g. "Configure outbound requests" and the previous item "Setting up Google AdMob" will be highlighted instead.

Tables have a couple styling issues;

• cell borders are missing (only top border seems to be there?)
• (optional) alternative row colors like GitHub does for readability

Comparison of docs.page vs GH markdown:

Unable to get Image zoom to work

I have tried to get feature Image zooming to work mentioned here:

https://use.docs.page/components#zooming

Not sure exactly what it is supposed to do, as I can see no feature on it on the docs page, nor when I try it.
It sounds like something that I would find useful if it does what I think it should be doing.

Tried with "zoomImages" set to both false and true, made no difference.

Reproduction docs repo:

Here is a test reproduction repo: https://github.com/rydmike/docs_page_test
and site: https://docs.page/rydmike/docs_page_test

This page contain a normal html link clickable image and also two zoom attempts, that don't do anything.

https://docs.page/rydmike/docs_page_test/another_page
its source: https://github.com/rydmike/docs_page_test/blob/master/docs/another_page.mdx

Having docs.json config file:

{
    "name": "DocsPageTests",
    "favicon": "/images/favicon.png",
    "logo": "/images/logo.png",
    "logoDark": "/images/logo.png",
    "theme": "#0x29B6F6",
    "zoomImages": "true",
    "noindex": "false",
    "sidebar": [
        ["Welcome",
            [
                ["Intro","/"],
                ["More intro", "/more_intro"]
            ]
        ],
        ["Zoom image", "/another_page"]
    ],
    "navigation": [
        ["Intro","/"],
        ["More intro", "/more_intro"],
        ["Package", "https://pub.dev/packages/flex_color_scheme"],
        ["Playground", "https://rydmike.com/flexcolorscheme/themesplayground-v5"]
    ]
}

This has been mentioned a few times, and would be a nice feature.

It could be done in various ways:

1. using typedoc-markdown-plugin to generate .md files, and formatting them from here (would have to do this for each language, and probably quite prone to errors imo)

2. writing our own plugin for typedoc etc (this is what docusaurus do, but potentially a lot of effort)

3. write some kind of parser of various generated json files into a common format for docs.page (potentially also a lot of effort)

Remove .text-white property to show text.

It would be really cool to support mermaid diagrams, there's a remark/rehype plugin but i believe it relies on puppeteer, not sure how this will interact with our bundler api.

New feature request - Embedded tweets

It would be useful if there was a feature to embed tweets, the same way you can use a custom component to embed YouTube videos.

Currently I have to make them as image screen shoots of the tweet and set a link on the the image to the tweet. This works, but is not as handy or nice. Not super critical, I can work with the image + link too. I would just prefer to embed a tweet, like below. This does does not work on GitHub either, but the code Twitter gives to embed a tweet is below:

FlexColorScheme V5-dev.2 is here 💙
With an even cooler config/code gen app https://t.co/3cgTNvoahH
Get the #Flutter package here https://t.co/oDheabOXIv Official v5 release coming when doc update is done.
This thread is still relevant and has more info:https://t.co/dS8jPAB53q pic.twitter.com/gxdCAjuJxl

— Mike Rydstrom 💙 (@rydmike) April 5, 2022

And it should end up looking like the image plus link version below. Well almost, this URL shows what the above should look like:

https://publish.twitter.com/?query=https%3A%2F%2Ftwitter.com%2FRydMike%2Fstatus%2F1511166732496429058&widget=Tweet

But close enough to this version:

https://melos.invertase.dev/commands/version 500

Types need to by reviewed and fixed, at the moment it has a few any and things need to be reworked a little.

Double quotes are being injected on quote blocks;

Shouldn't be the case? Shouldn't it be up to the user to add these?

The PR/branch preview bot needs implementing

Comparing the content width to GH markdown it's a lot thinner in width (GH to me feels a lot easier to read) :

Changing the article classes attribute to prose dark:prose-dark px-6 lg:px-6 py-6 desktop:py-20 mx-auto max-w-5xl improves this quite a bit:

Note the additional px padding change too added above to the classes attribute edit which improves mobile:

Before padding change:

After padding change:

The styling of the documentation doesn't feel super readable right now. Some quick wins:

• Remove header borders
• Remove sidebar border (or make less obvious)
• Compact items in the sidebar
• Indent sub-menus in the sidebar
• Update Dark Mode colours - more gray and less blue
• Add transitions to hover elements

I'm sure that there is an error from my side but I don't know what it is, because I'm not able to see the exception anywhere.

I'm trying to build the doc for https://github.com/vincenzopalazzo/changelog.dart and I configured the repository as the doc suggested. However, I receive the following error https://docs.page/vincenzopalazzo/changelog.dart

Any idea?

Feature: Use different highlight "theme" color for light and dark mode.

Currently the same customizable color is used as highlight "theme" color for both light and dark mode. This is not ideal, since there are very few and limited color options that work well in both dark and light mode as a highlight "theme" color.

It would be useful if it was possible to specify separate custom colors for light and dark mode highlight color.

On the bottom of every page is broken, goes to a 404 on GitHub

• getting a logged error on certain routes. This is a remix resource route for optional css (for e.g Katex)

For the custom components functionality you have shown it is possible to use tabs, however the tab content is not shown at all.

This can be replicated on the components page itself in the docs.page documentation.

For some reason the active link in the sidebar isn't correct server-side. On client navigation it seems to be correct.

If a branch ref looks like a PR ref and there's no PR ref it should fallback to the branch ref

e.g

https://use.docs.page/~123

Local preview mode doesn't seem to be working in Chrome.
After selecting the directory, then accepting the permissions, nothing happens.

The prism-react-renderer only includes the following languages:
https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js

I would like to have support for dart code highlighting. It can be easily added as prism already supports it and it is explained how to implement it in the first question How do I add more language highlighting support?
https://github.com/FormidableLabs/prism-react-renderer#faq

We think this tool is amazing to use for the upcoming stripe package: flutter_stripe. But we consider this an obstacle for using it with our docs.

Hello, loving docs.page so far and already using it for my project!

I do have one request which is to support markdownlint control comments such as:

<!-- markdownlint-disable -->

or

<!-- markdownlint-restore -->

While trying to utilize the Tabs component for example, this is useful to wrap the content of the inner TabItem content which gets linted/formatted and breaks markdown styling as it attempts to get HTML-formatted.

Currently when attempting to use these control comments you get a broken page (at least with docs.page/preview).

• All quick links to docs.page docs are incorrect.
• The ←Go to docs.page link - shouldn't this go to the root documentation for the current repository?
• The report an issue. link - shouldn't this be reporting an issue on the current repository - rather than on docs.page
• No page title
• UI mode selector appears twice:
  

More a nit picking than anything but GH H1s and H2s also add a horizontal line underneath which seems to break up the content a bit better:

docs.page:

vs GH:

Error in sidebar doc example

The documentation for sidebar in the docs says navigation instead of siderbarin the example:
https://use.docs.page/configuration#sidebar

navigating through sidebar on live preview mode doesn't reset scroll position, but it should

Custom domains were working via a proxy, however we ran into some (semi-expected) issues:

• Since pages are built statically, the href is a static value based on the properties of the basic path.
• We assumed that if you have a custom domain setup, you will only use a custom domain and not the docs.page generation.
• The URL for a ref was a bit odd, e.g. https://melos.io/~docs-updates/commands/bootstrap

Configure Image Caption Spacing

Is it possible to configure the spacing between Image and its caption?
If so, how? If not, is it possible to introduce the capability?

The spacing is very large now, I would prefer it to be much smaller.

Reproduction docs repo:

Example can be seen here: https://docs.page/rydmike/docs_page_test/another_page

Here is a test reproduction repo: https://github.com/rydmike/docs_page_test
and site: https://docs.page/rydmike/docs_page_test

Having docs.json config file:

{
    "name": "DocsPageTests",
    "favicon": "/images/favicon.png",
    "logo": "/images/logo.png",
    "logoDark": "/images/logo.png",
    "theme": "#0x29B6F6",
    "zoomImages": "true",
    "noindex": "false",
    "sidebar": [
        ["Welcome",
            [
                ["Intro","/"],
                ["More intro", "/more_intro"]
            ]
        ],
        ["Zoom image", "/another_page"]
    ],
    "navigation": [
        ["Intro","/"],
        ["More intro", "/more_intro"],
        ["Package", "https://pub.dev/packages/flex_color_scheme"],
        ["Playground", "https://rydmike.com/flexcolorscheme/themesplayground-v5"]
    ]
}

https://github.com/invertase/docs.page/pull/156/files#diff-e7032d255aae7d178d0ce1547e9bd1f48e708209c1f95c866cde6d5a53b1ac5fR127

Here we're throwing a custom error if the bundle request fails, this should be handled properly

as well as the move to remix we added a bunch of features that require documentation, not limited to:

• live preview mode
• locales
• typedoc cli

middleware can modify host name, see if we can use this for custom domains, might be better than what we currently do

Images on the markdown on this page specify a height attribute which GH markdown parses successfully as seen on the right, docs.page strips it out as seen on left

Unable to use a custom favicon

I have tried to get a custom favicon to show up, but have been unable to do so. Either the feature is broken, or I need more advice.

• Tried repo relative link to used favicon.png
• Tried absolute URL link to used favicon.png

In neither case have I been able to produce a favicon.
The used favicon is a copy of one that works when page/app is published elsewhere.

Reproduction docs repo:

Here is a test reproduction repo: https://github.com/rydmike/docs_page_test
and site: https://docs.page/rydmike/docs_page_test

No custom favicon is shown, the logos works fine though.

Having docs.json config file:

{
    "name": "DocsPageTests",
    "favicon": "/images/favicon.png",
    "logo": "/images/logo.png",
    "logoDark": "/images/logo.png",
    "theme": "#0x29B6F6",
    "zoomImages": "true",
    "noindex": "false",
    "sidebar": [
        ["Welcome",
            [
                ["Intro","/"],
                ["More intro", "/more_intro"]
            ]
        ],
        ["Zoom image", "/another_page"]
    ],
    "navigation": [
        ["Intro","/"],
        ["More intro", "/more_intro"],
        ["Package", "https://pub.dev/packages/flex_color_scheme"],
        ["Playground", "https://rydmike.com/flexcolorscheme/themesplayground-v5"]
    ]
}

Learn more buttons on the home page 404'ing:

Most of the sidebar links on docs are 404'ing: