The docs from commitd

Presentation

Add the ability of a markdown page to be treated like a slide show.

Suggest

----

slides: true
usual stuff
----

# Slide 1

---

# Slide 2

The slide would be rendered in the content pane when clicked on. This approach has the benefit that:

We can embedded slides into our slides. They are probably very good for 'getting started' content. Ideally the side menu could be optionally hidden.
We use the same plugin for single presentation (if there's only one page the side menu should be auto hidden).

For inspiration.

Possible formidable spectacles, etc could be used for rendering.

Can type incorrect path and still work but breaks links

Use index.md(x) within a nested directory

Current behaviour allows:

nested.md <- matches name of dir
nested/
   hello.md

Allow index.md to be used instead

nested/
   index.md <- same content as nested.md above
   help.md

Benefit is that the documentation will still work if nested (dir) is renamed. Also it keeps content about nested under nested/.

Images are missing

html is there so looks like a styling issue

Keyboard shortcuts

At least:

Prev / Next page (arrows left/right)

Possible

Prev/Next section (directory - arrows up/down)
Toggle side menu
Home

Add @commitd npm setup instructions

Or move to npm?

Print should have "" not null as defaults

Otherwise it doesn't exist

Some mermaid diagrams go outside the container.

First fix to remain in the container, then consider if a specific size can be specified.

Fix 'Possible EventEmitter memory leak detected' error

MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 SIGHUP listeners added to [process]. Use emitter.setMaxListeners() to increase limit

Stop emphasis and Bold creating new paragraphs

when using em or bold you get new paras rather than spans.
Note this issue may need to be fixed in components.

Fix mermaid gantt chart rendering

Looks squashed - possibly due to the size settings applied
by the gatsby-mermaid-plugin.

Arrow heads not rendering in mermaid diagrams

For example, this should render an arrow head but does not:

```mermaid
graph TD
first --> second
```

Separate components and queries

This will allow simper substitution of the components

Move to semantic-release

What problem do you want to solve?

Automate the release process

What do you think is the correct solution to this problem?

Use semantic-release

Internal links within markdown don't work

It's not clear this they should do but:

### Title

This links to [Other](#other)

### Other

This links to [Previous](#other)

This creates links but those links don't work. In fact they go back to the home page.

No id is created on titles - this is likeky a remark thing.

MDX / MD issue (Index.html is not built on new projects)

What happened?

Mdx vs Mx seems to have broken Markdown only sites.

If you have docs/index.md then index.html is not generated when built. So the resulting site is totally broken, although development seems to work.

If you have docs/index.mdx then you get an index.html.

I also get numerous errors (with 3.14):

warn The GraphQL query in the non-page component "/app/node_modules/@committed/gatsby-theme-docs/src/layout/docs.tsx" will not be run.
Exported queries are only executed for Page components. It's possible you're
trying to create pages in your gatsby-node.js and that's failing for some
reason.

If the failing component(s) is a regular component and not intended to be a page
component, you generally want to use a <StaticQuery> (https://gatsbyjs.org/docs/static-query)
instead of exporting a page query.

If you're more experienced with GraphQL, you can also export GraphQL
fragments from components and compose the fragments in the Page component
query and pass data down into the child component — https://graphql.org/learn/queries/#fragments

And then basically no pages output.

What did you expect to happen?

md and mdx behave the same.

Any relevant technical information (OS, versions, logs)?

gatsby 3.14.5, node 16 and docs 3.1.0.

Note this works on gatsby 3.8.0, so must be an API change.
However, I have found it almost impossible to get 3.8.0 pinned with npm. When running Docker npm ci I often get 3.14 which causes this bug to occur.

Possible related:

gatsbyjs/gatsby#21843. I can confirm that added srcpages/index.js to the docs template (in node_modules) dir does render apage. So I assume this is the fix, however, I'm not entirely sure what to put that file. It's not the content of layout/index.js.
https://stackoverflow.com/questions/55564792/no-index-html-file-after-gatsby-cli-build

Add breadcrumb

Add @commitd/components tables

The default table rendering does not look good.
But the Table doesn't easily support the markdown.

Add title page to print view

Search deoes not work

I can see the index is created and it arrives at the Search component, the actual stuff does not return any results.

Possibl worth trying a new search engine - that ones doesn't look too active and is a fork of a dead project.

Mermaid stateDiagrans with fork join don't render

Probably an issue upstream with remark / mermaidjs plugin, you can't use fork join in the stateDiagram.

Example (from the mermaidjs website)

```mermaid
 stateDiagram
    state fork_state <<fork>>
      [*] --> fork_state
      fork_state --> State2
      fork_state --> State3

      state join_state <<join>>
      State2 --> join_state
      State3 --> join_state
      join_state --> State4
      State4 --> [*]
```

I suspect this is something to do with the <<

Warning: The tag <undefined> is unrecognized in this browser. If you meant to render a React component, start its name with an uppercase letter.
    in undefined (created by MDXCreateElement)
    in MDXCreateElement (created by MDXContent)
    in wrapper (created by MDXCreateElement)
    in MDXCreateElement (created by MDXContent)
    in MDXContent (created by MDXRenderer)
    in MDXRenderer (at Markdown.tsx:30)
    in MDXProvider (at Markdown.tsx:12)
    in Markdown (at docs.tsx:16)
    in main (at Layout.tsx:84)
    in div (created by ForwardRef(Container))
    in ForwardRef(Container) (created by WithStyles(ForwardRef(Container)))
    in WithStyles(ForwardRef(Container)) (at Layout.tsx:83)
    in main (created by Content)
    in Content (at Layout.tsx:82)
    in div (created by Root)
    in Root (at Layout.tsx:59)
    in div (created by ThemeProvider$1)
    in ThemeProvider (created by ThemeProvider$1)
    in ThemeProvider$1 (at Layout.tsx:52)
    in Layout (at docs.tsx:15)
    in _default (created by HotExported_default)
    in AppContainer (created by HotExported_default)
    in HotExported_default (created by PageRenderer)
    in PageRenderer (at json-store.js:93)
    in JSONStore (at root.js:51)
    in RouteHandler (at root.js:73)
    in div (created by FocusHandlerImpl)
    in FocusHandlerImpl (created by Context.Consumer)
    in FocusHandler (created by RouterImpl)
    in RouterImpl (created by Context.Consumer)
    in Location (created by Context.Consumer)
    in Router (created by EnsureResources)
    in ScrollContext (at root.js:64)
    in RouteUpdates (at root.js:63)
    in EnsureResources (at root.js:61)
    in LocationHandler (at root.js:119)
    in LocationProvider (created by Context.Consumer)
    in Location (at root.js:118)
    in Root (at root.js:126)
    in MDXProvider (at wrap-root-element.js:65)
    in MDXScopeProvider (at wrap-root-element.js:64)
    in Unknown
    in Unknown (at wrap-root-element.js:72)
    in _default (at app.js:67)

Add contents view

A right hand column showing the header structure of the page

Mermaid stateDiagram font size

What happened?

What did you expect to happen?

Font to be smaller.

Might need to test other diagram types (the sequenceDiagram seems fine) but perhaps this is that particular instances.

Any relevant technical information (OS, versions, logs)?

Firefox

Use title case for directories in sidebar

Nested Directories will typically be lowercase (or likely hyphened lower-cased). Currently this is rendered as is.

The out of the box experience of sidebar could be improved using formatting with title case (or sentence case).

Can be achieved with https://www.npmjs.com/package/change-case

const title = changeCase.titleCase(directoryName)

Ignore mailto in link checker

Add @commitd/components shortcodes

This would allow the components to be used in the
mdx without specific imports

LInks with .md

What happened?

In Github you have to have .md at the end of a link to navigate, otherwise you get a 404.

e.g. [Link](../another/page.md).

VS Code supports with or with .md.

Docs will 404 if you have the .md.

What did you expect to happen?

I want Docs to behave like VS Code - ie if the link is .md it should be stripped off in Docs.

Then I can navigate the same site in either Docs, via VS Code, or via GitHub.

Any relevant technical information (OS, versions, logs)?

Inbuilt search

Nice to have search index. This would help save our linking everything together, and generally aid the user.

Ideally, this would be offline.

This could start with simple filtering of the side bar (see semantic https://react.semantic-ui.com/)

Then moved to content based search: Docusaurus uses agolia search which is online.

See Gatsby documentation https://www.gatsbyjs.org/docs/adding-search/

Or at least the current selection should be visible (in the middle)

Improve README / setup

Might be just me but setting up wasn't that smooth:

Needs a.gitignore (at least with nodemodules, .cache and public)
Complains about print section
Needs a gatsby-config.js would be nice to have a default there

The gatsby-config.js in the readme is not sufficient:

I wonder if it's possible to have this done automatically when you yarn add?

Perhaps it could be generated queried and then either enabled / disabled by something in the front matter, or perhaps smart based on the number of headings and/or size of the document?

Perhaps it could be put in a right sidebar.... then it's responsively displayed if width allows.

commitd / docs Goto Github PK

docs's Introduction

commitd

docs's People

Contributors

Stargazers

Watchers

docs's Issues

Recommend Projects

Recommend Topics

Recommend Org