ibm / nicedoc.io Goto Github PK

Data

• Latest version
• Latest commit
• Monthly downloads
• Stars/watches

Inspiration

• https://github.com/egoist/version-badge
• https://github.com/klaussinani/rels

example: https://nicedoc.io/jamiebuilds/babel-handbook

🚨 You need to enable Continuous Integration on Greenkeeper branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please click the 'fix repo' button on account.greenkeeper.io.

We can improve the transition between themes.

Current version

Version with transition

All images not loading.
https://nicedoc.io/hsgw/plaid/blob/master/doc/en/soldering.md

https://github.com/fat/zoom.js

Would be nice to automatically integrate codeblocks in the readme with RunKit so user's are one click away from trying them out.

Hello,
your website states:

Compatible with any markup format.

I use AsciiDoctor, but I get a 404 and it states that the repo doesn't exist.
The website says that I should use the format: nicedoc.io/:org/:repo[@:ref]

when I do that for my repo, it would be: nicedoc.io/kreait/slack-spring-boot-starter
then, the error says that the repo github.com/slack-spring-boot-starter/kreait doesnt exist.
(org and repo are swapped)
so I tried to change the nicedoc URL to nicedoc.io/slack-spring-boot-starter/kreait
but the error stays the same.
it would be great if you have a hint on how to get the correct documentation, thank you!

The purpose of this issue is to collect beautiful repositories that we can use as the reference to convert them into fancy readme.

They can used for testing purposes as well

https://github.com/jamiebuilds/react-loadable
https://github.com/substack/stream-handbook
https://github.com/jsdom/jsdom
https://github.com/cheeriojs/cheerio
https://github.com/jamiebuilds/babel-handbook
https://github.com/GoogleChromeLabs/quicklink
https://github.com/anubhavsrivastava/awesome-ui-component-library
https://github.com/cyrilwanner/next-optimized-images

Inspired in rauchg's blog count views

Related:

• https://github.com/rauchg/blog/blob/68c46cb9586b292c735c333f1a129905fbe0c98c/lib/with-views.js#L20
• https://github.com/rauchg/blog-views

Investigate how we can provide some insights about how to improve the READMe of any project

$ friction
/repo
 [ERROR] README not found                see http://git.io/yHosNA
 [ERROR] CONTRIBUTING guide not found    see http://git.io/g_0mVQ
 [ERROR] ISSUE_TEMPLATE not found        see http://git.io/vgpaA
 [ERROR] PULL_REQUEST_TEMPLATE not found see http://git.io/vgpVk
 [ERROR] CODE_OF_CONDUCT guide not found see http://git.io/vJvR3
 [ERROR] LICENSE not found               see http://git.io/pFMQMQ
 [ERROR] Bootstrap script not found      see http://git.io/jZoRYA
 [ERROR] Test script not found           see http://git.io/oo21Jw

Related

• https://github.com/rafalchmiel/friction
• https://demos.algorithmia.com/github-readme-analyzer/
• https://www.yegor256.com/2019/04/23/elegant-readme.html

• https://codepen.io/shubniggurath/pen/GGXKJe

I saw https://www.pkgstats.com/pkg:remark-parse and it looks interesting. That’s only for npm though. But by tracking the GitHub dependency graph every day or so, it could be displayed for more languages.

large viewport version

small viewport version

(sketch design)

Considerations

Expand subsection

Note how in the screenshot We are at Custom Endpoints subtitle inside Tips.

Because we are there, the Table of Content is showing subtitle inside Tips.

So the Table of Contents natural state is just showing the main titles. As soon as you are reading a subtitle, the subtitles are expanded.

Section has is reflected into the URL

In that case, because you are reading Custom Endpoints, the nicedoc url reflect that with the proper hash.

As soon as you read a different section, the hash into the URL will be updated for reflecting that.

Also, if you click into the GitHub icon for seeing the original README at GitHub, the url contain the hash as well.

Small Viewport

When the viewport is not enough big to place the Table of Contents properly it will be placed inside a lateral aside associated with a burger menu.

Inspiration

• https://metascraper.js.org
• https://www.pullandbear.com/es/mujer-c1010141503.html
• https://docute.org
• https://github.com/docsifyjs/docsify/search?q=active&unscoped_q=active (scroll effect)

Investigate if we can use a (free) proxy image service for removing background images

Related:

• https://images.weserv.nl

• http://localhost:3000/kikobeats/voll

It could be very interesting if the tool allows us to export to epub format ;)

Change text color to the table's headers to improve the contrast.

Although we are not shipping a way to customizing the style, we can provide more themes to be possible to adjust your personal taste.

Note we are using styled-system under the hood, so potentially it should be easy to do

Related

• https://styled-system.com/guides/color-modes
• https://devhubapp.com
• https://github.com/devhubapp/devhub/blob/d29ffc8196446daec2e5c8e97db682b5484df74a/packages/components/src/styles/themes.ts

remark/rehype and other unified things are used here. Most of the code related to it is in the build/ directory.

@Kikobeats asked if I could review the code, so here goes, in an unordered list of things I came across.

Tips

Cheerio not needed

Everything cheerio is used for, rehype can also do. Cheerio is often easier, because it’s like the DOM, and thus more familiar to developers. It’s also used more, so probably less buggy. However, it’s heavy to load, and so is rehype, and functionalities overlap, so it’s probably better to pick one.

Move stuff to plugins and utilities when possible

...and publish them! So the rest of the unified community can benefit from them as well!

Is markdown linted?

A linting preset is used, is that needed? What’s done with the lint warnings?

Don’t use remark-html

https://github.com/IBM/nicedoc.io/blob/master/core/build/html.js

remark-html is essentially remark-rehype and rehype-stringify combined. But the downside is that you can’t use other rehype plugins in combination with it. So you need to parse the document again. Which is what’s happening in html.js.

You can instead use one processor like so:

export default async data => {
  const { contents: html } = await unified()
    .use(remarkParse)
    .use(remarkRehype)
    .use(rehypeSlug)
    .use(rehypePrism, { ignoreMissing: true, preLangClass: false })
    .use(rehypeStringify)
    .process(data)

  return html
}

Use unified instead of remark or rehype directly

remark is unified + remark-parse + remark-stringify, rehype is unified + rehype-parse + rehype-stringify. If you’re using a different -stringify, such as rehype-stringify, you are loading an unneeded stringier (remark-stringify).

If you use unified directly, it’s more explicit which parser and stringifier is used! And you won’t duplicate them.

unified supports promises!

No need to use util.promisify, .process(data) without a callback already returns a promise!

• https://github.com/thedevelobear/react-rewards
• https://github.com/microlinkhq/microclap

Currently, the default value is light.

Could be nice to detect if the default value should be dark based on prefers-color-scheme

We can use a react hook for that: https://github.com/donavon/use-dark-mode

We are using prism syntax highlight and the language alias are different than default alias by GitHub.

Currently, if an alias is not resolved, it throws an error, causing a 500 error in the view.

Unknown language: `sh` is not registered
Error: Unknown language: `sh` is not registered
    at Refractor.highlight (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/refractor/core.js:89:13)
    at visitor (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/@mapbox/rehype-prism/index.js:29:26)
    at overload (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit/index.js:27:12)
    at one (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:29:16)
    at all (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:53:25)
    at one (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:37:14)
    at all (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:53:25)
    at one (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:37:14)
    at all (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:53:25)
    at one (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:37:14)
    at all (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:53:25)
    at one (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:37:14)
    at visitParents (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit-parents/index.js:22:3)
    at visit (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/unist-util-visit/index.js:22:3)
    at tree (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/@mapbox/rehype-prism/index.js:11:5)
    at wrapped (/Users/josefranciscoverdugambin/ibm/nicedoc.io/node_modules/trough/wrap.js:25:19)

Related: mapbox/rehype-prism#6

Investigate how we can add search capabilities for any enough long documentation file.

Related

• https://github.com/nextapps-de/flexsearch

With a floating header, anchors to specific parts of the page are hidden behind the sticky bar, for example this.

There might be a CSS-based enhancement available to address this, but I haven't used scroll-padding before and I don't know how well it's supported, but at least for the browsers which do support it the experience should be much better.

We are considering the default branch is master

That's a thing not true. Also, GitHub provide an endpoint for getting the default branch: https://stackoverflow.com/a/16501903

The GitHub API is exposing an endpoint for getting the readme of a repository:

https://developer.github.com/v3/repos/contents/#get-the-readme

example: https://api.github.com/repos/octokit/octokit.rb/readme

Then, we can fetch the download_file content.

Ideally, we want to get the HTML version of the markdown. That's could be done using media-types.

Another thing to consider is that the GitHub endpoint is returning the README for the master branch by default, doing that configurable using ref parameter.

We can reflect that as part of the app route:

• /kikobeats/osom → Get README from master branch.
• /kikobeats/osom@next → Get README from next branch.

The theme mode works saving a variable into localStorage.

Currently, there is not a way to update the value without entering in the website and toggle the theme selector.

It could be easily done retrieving the value for query string

https://nicedoc.io/Kikobeats/voll?theme=dark
https://nicedoc.io/Kikobeats/voll?theme=light

Why do you need Sass for this project?

If you have PostCSS as a dependency, you can use postcss-preset-env to write CSS standard ( aka Vanilla CSS )

Hey, 👋

License is not always shown, even if it's specified. Example:

https://nicedoc.io/substack/stream-handbook
https://github.com/substack/stream-handbook/blob/master/LICENSE

It would be also great to see a license if it's specified in package.json file (example) or even in readme (example).

The side menu for https://nicedoc.io/ibm/kui is not working properly

The menu is using this kind of links #user-content-quick-install but the correct one should be just #quick-install.

• https://commento.io
• https://gitlab.com/commento
• spectrum.chat integration?
• https://comntr.github.io/about/

current

expected

Probably easy to do after #12

I use <br> for hard linebreaks, but Nicedoc doesn't render them.

GitHub:

Nicedoc:

From: https://nicedoc.io/sindresorhus/got

When trying to use nicedoc.io to render Github repo that does not exist or are not public (for example https://github.com/google/tensorflow, which returns a 404), nicedoc returns error 500 instead of a 404 (https://nicedoc.io/google/tensorflow).

The current markdown processing workflow is:

1. Getting MD for the GitHub API endpoint.
2. Convert it into HTML.
3. Monkey patching some things
   3.1 Convert links into absolute links
   3.2 Add anchors links
   3.4 Add zoom for images
   3.5...

Most of the monkey patching things can be done using remark plugins.

Also, it allows us do more powered things in order to normalize the content.

• remark-autolink-headings: auto anchors links.
• remark-capitalize: Sensible good titles
• https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-autolink-headers
• remark-emoji: replace :emoji: to real UTF-8 emojis in text.
• https://github.com/remarkjs/remark-external-links
• https://github.com/remarkjs/remark-github
• https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-smartypants
• https://github.com/remarkjs/remark-license
• https://github.com/remarkjs/remark-normalize-headings
• https://github.com/zslabs/remark-relative-links
• https://github.com/remarkjs/remark-strip-badges
• https://github.com/remarkjs/remark-toc

moar at https://github.com/remarkjs/awesome-remark

What's happening

When I click on any link present on this README that is hosted on the Github repo itself, I got an error 500.

Maybe it's a consequence of the fact that Github adds blob/master to the file path, because if I remove that slug, things go perfect.

This issue maybe also related to #40

What's supposed to happen

Regardless the place where I am reading the documentation (Nicedoc or Github), every link should work properly.

Right now the code languages supported are the languaged bundled by default by refractor.

We need to generate a bundle with the same languages at GitHub.

Also, refractor added recently support for aliases, so both things mean we can make a 1:1 translation

(or don’t always work)

Take the readme of franc, https://nicedoc.io/wooorm/franc, at the bottom it links to the LICENSE file.
nicedoc generates a link with href="LICENSE" from that, which on nicedoc goes to https://nicedoc.io/wooorm/LICENSE (a 500 which should be a 404?)

Also thanks for using remark and unified!! 🤗