vectordotdev / gitdocs Goto Github PK

• checks for existing docs and adds a .gitdocs config file if necessary
• if no docs, it generates a docs folder with proper examples/boilerplate

Could do this with a custom component, but would be great to be able to render shortcuts like this https://cl.ly/233J0J1F0L3D.

If the sidebar is open or navigated to a subsection, on reload that section will be folded. I would expect it to retain the same state, and be open the currently displayed subsection.

When clicking a top level header, it should append the location as a hash to the url so that I can link others to a certain part of the document. The way GitHub does it would work well, when you hover you actually see a little link icon: https://cl.ly/0L0I1B14180X.

If I'm in a file called usage/index.md I should be able to create a markdown link to /logging.md and have that automatically route to docs/usage/logging.md.

*edit: would also be good to be able to reference "absolute" doc urls like /docs/usage/logging.md from any other doc.

I created an index.md file under a directory and saved it while dev server was running. The file did not have a heading, and in that case I think failed to render but no error message was surfaced or received. I would expect to see a log line or warning or something to indicate I did something wrong.

• info
• warning
• danger
• success
• button

Prenote: I don't use a docs.json for my tests.

In my docs I have a common 'assets' directory, containing all my imagery.

assets
imageA.png
fileA.md
folderA
fileB.md

To link imageA.png from fileA.md I use:

![](assets/imageA.png)

To link imageA from fileB.md I use:
![](../assets/imageA.png)

Both fail to link and both files are linked against:
/assets/imageA.png

You can also check this in your docs at markdown.md#links

Could be cool to have a --pdf flag for the build command that will output to a pdf rather than a static site. Useful for research papers, etc.

https://github.com/RelaxedJS/ReLaXed

Title is pretty self-explanatory, it just hangs.

I just installed git docs globally with yarn, then get this error when running gitdocs init. Is there another dependency I need installed? I'm assuming it's something to do with babel, but my understanding is that babel best when installed per project opposed to per device (https://babeljs.io/docs/usage/cli/). I may just be missing something here.

npm -v
5.6.0

node -v
v9.5.0

Would be great to add various languages and be able to switch between them.

I don't think the docs output should be prefixed with a dot, it's not a reserved folder it's something you specifically want to deploy.

Just an idea, there is some documentation I'd like to add but don't want it to be public yet. Supporting a draft status in the front matter that wouldn't display the doc in the navigation would be nice.

Now that we have a lint command, yarn lint, and a test command, yarn test we should run these on a CI for every commit to master and every PR.

If you change a directory name and reload the site while on that path, the server will crash. While we would expect an error since that path no longer exists, I think it should be gracefully handled as the paths are used to generate links and navigation menus. I feel like changing these names will be part of a standard editing workflow.

Should use the git repo src from docs.json

The following link format fails to render as a link, it is only rendered as text.

[Link]

[Link]:google.com

It would be nice to see how gitdocs stacks up against docusaurus, gitbook, docsify, etc.

• custom components (tips, highlight, mermaid, etc)
• bring your own components (in progress)
• support for prism & highlight.js
• progressive react app (allows for interactive components and fast browsing speeds)
• statically rendered (great for seo)
• true routes (no hash routing)
• automatic table of contents
• automatic site generation based on folder structure
• infinite documentation nesting

Should copy contents of _static into the output folder during serve and build. Add it into the connect middleware for the server.

Add the ability to switch between versions of docs.

Add default themes you can choose from using your docs.json

Somethings (obviously) missing 😉

Any idea?

Andy

`/usr/local/lib/node_modules/gitdocs/node_modules/yargs/yargs.js:1100
else throw err
^

Error: Command failed: cd node_modules/gitdocs && node_modules/react-static/bin/react-static start
at checkExecSyncError (child_process.js:601:13)
at execSync (child_process.js:641:13)
at Object.handler (/usr/local/lib/node_modules/gitdocs/bin/gitdocs.js:32:7)
at Object.runCommand (/usr/local/lib/node_modules/gitdocs/node_modules/yargs/lib/command.js:228:22)
at Object.parseArgs [as _parseArgs] (/usr/local/lib/node_modules/gitdocs/node_modules/yargs/yargs.js:1013:30)
at Object.get [as argv] (/usr/local/lib/node_modules/gitdocs/node_modules/yargs/yargs.js:957:21)
at Object. (/usr/local/lib/node_modules/gitdocs/bin/gitdocs.js:72:3)
at Module._compile (module.js:635:30)
at Object.Module._extensions..js (module.js:646:10)
at Module.load (module.js:554:32)`

Uncommon filenames don't link
e.g. "Props vs. State.md"

Not sure what the correct way to act on these files is: but at least there should be an error thrown...

Would be nice to have an interpolated syntax for previewing components definitions, related to #9.

Add warnings during build time if links are dead.

When a new directory is added, it is not reflecting on reload. I would expect the documents or path to get created.

1. Added a file
2. Restarted my gitdocs server
3. Reloaded the page
4. Sidebar does not reflect folder structure

• Site: https://cl.ly/3U0r2L2X0J2j
• Files: https://cl.ly/2z05402P1s1u

When building the manifest, check for this before assuming the url based on the file structure. Also put in a check to prevent duplicate urls.

Both vertical and horizontal window resizing causes page reflow, and for some reason, causes images to reload completely as well. My guess is something to do with the responsive size detection and rerenders. You can see it if you go to react-static.js.org and resize the window, though it's much worse on mobile.

There is nothing in express.md, I would just expect to see a blank page.

https://cl.ly/140H3u1Y3m0o

Every html file that is output has the exact same style tag inside of it, this should probably just be shared for optimal build speeds https://cl.ly/341W0z1W052h.

I would expect GitDocs to find the root and use my /docs folder instead of having to cd in there.

Both are very common, I've mistakenly typed start a few times—I think they should both just run the same command.

Some inspiration:

• gatsbyjs/gatsby#312 (comment)
• https://www.npmjs.com/package/reactdown
• gatsbyjs/gatsby#3012
• http://md-to-react.surge.sh/
• https://github.com/fazouane-marouane/remark-jsx/tree/master/packages/remark-custom-element-to-hast

When working on #38 I noticed that all possible components are included in the built file. These components are used https://github.com/timberio/gitdocs/blob/master/src/components/Markdown/index.js#L24-L34

As we add new, more complex components, we should either:

• Use code splitting to only load libs when needed
• Only include the react components that are used. If we provide a <Video> component, then it should only be included in the bundle if we actually found one from the markdown files

Somewhat popular and powerful text based formatting lang, supported by readthedocs.org.

While working on porting some docs, I noticed this would be helpful. I'd like to be able to run something like gitdocs add node/http and automatically have a file generated at that route for me, pre-filled with appropriate front matter.

Could do this client-side for now, but maybe provide a plugin for algolia.

I have these external URLs I would like to link out to, but don't want to render any documentation for them: https://cl.ly/0a101f1C3C20.

Instead of generating a full static site with folders/subfolders this could work like docsify.js.org and be ideal for deployment on github pages.

Currently there is no license attached to this repo.