intuit / ignite

Modern markdown documentation generator

Ignite

Modern markdown documentation generation.

Usage

Head over to the full documentation for a guide on getting started with Ignite.

Contributing

Developing

To start developing Ignite, start up a terminal and run the following command. Be sure to restart the dev server when changing any non-React or non-markdown file, since webpack doesn't handle them.

yarn build:lib && yarn start

Debugging

To debug your build run

yarn build

Then use your favorite HTTP server to emulate a server environment.

python -m SimpleHTTPServer

NOTE: All urls are relative to options.baseURL. Make sure to change baseURL if your website isn't served from '/'.

Publishing

Releasing and publishing are handled automatically. Any time a PR is merged or code is pushed to master a new version of Ignite is released along with publishing a new version of the documentation to GitHub Pages.

Pull Requests welcome! Submit any bug report or feature enhancement as an issue.

Contributors

Thanks goes to these wonderful people (emoji key):

Andrew Lisowski 💻 🎨 📖 💡 🤔 🚇 📦 👀 ⚠️	Adam Dierkens 💻 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

Awesome Plugins:

⭐ Prop-Types - Takes a react component and displays a table with its prop-types.

⭐ JSON Schema - Takes a JSON-Schema and exposes a Component that matches ids to auto-generate docs.

🚀 If you want to add your plugins to this list make a PR! 🚀

Gallery

💅 Have some beautiful docs built using Ignite? Make a PR and feature them here 💅

ignite's Issues

switch to uglifyjs alternative

V2

• Tappable
• break into tinier packages (monorepo)
• make static functionality a plugin?
• build on next?

Inline Editor

allow user to edit markdown in the documentation website

add .igniterc docs

Make dev build faster

rework webpack configs to on do whats needed for the dev build

Flexbox bug with brand padding

Original writeup: #66 (comment)

Ok so an update, I think I've narrowed it down, and AFAICT it's a bug related to the fallback display property on .navbar-item. This was happening on master as well, so it's not something I introduced in this branch. It's just more noticeable on this branch because of the element changes (which reduce padding slightly).

The easiest way to repro is to:

Open dev tools on the side of the window
Shrink the viewport slightly larger than the 768 breakpoint
Close dev tools
Reopen dev tools

And the issue is present. As soon as you reload the page, it resolves. Here's what it looks like happening in real time on this branch:

And this is what is looks like happening on the master branch

It's up to you whether or not you want to proceed with merging this. I'm going to open up a separate issue for this problem.

I have a strong hunch that the issue has to do with the webkit fallback settings on the display property of the .navbar-item class.

Specifically, the -webkit-box. The reason for that hunch, is, when loading the window, the navbar-item is 123.16px wide and during the bug the width is 105.69px. After reloading the page to reset the width back to 123.16px, if you disable the css declaration display: flex (which activates the fallback, display: -webkit-box, the width drops down to 105.69px, the same width that's present during the above bug.

But unlike when the bug is present, when that fallback is activated the spacing between the logo and the header is reduced, so the padding is shrinking proportionately

This issue is almost like the fallback declaration is getting combined with the display: flex declaration. Super weird stuff. It's worth investigating whether this is a bug present in bulma or if it's something specifically with the styles defined in Ignite. The navbar is using hardly any custom styles and is basically stock bulma.

Autocomplete on search field

might not be easily possible with current implementaion

try out babel-plugin-preval

might be able to move some code out of 'generate.js' and 'html-to-jsx.js' using this

Try flat file structure and add example to examples folder

Search Results should use markdown renderer

might need to include all html and map markdown hits to that.

be careful about increasing the bundle size too much

Double scroll-bars in side menu (windows chrome)

The ignite docs end up showing multiple scroll bars on windows

Readme contains link to Ignite docs, that link is 404ing

In the usage section, there is a link to https://intuit.github.io/Ignite/, which is currently a 404. Looking at the gh-pages branch it looks like there is an extra path level introduced and https://intuit.github.io/Ignite/Ignite does resolve, although most resources on the page are pointing at https://intuit.github.io/Ignite/. and 404ing themselves, which leads me to believe that the extra Ignite path is the issue.

Right hand table of contents for page

Something like https://docs.gitbook.com/hosting/custom-domains

Smarter Embed

codepen embed
Medium article

Smarter embed? maybe we can be more generic

Edit on github

Add Edit on Github button on every pages.

A plugin to generate a button Edit on Github on every page that when clicked will open the corresponding md editing page on github.

similar to - https://github.com/njleonzhang/docsify-edit-on-github

Proposal: support custom domains with ignite --deploy

So GitHub is a bit picky when it comes to deploying with custom domains. Instead of having a persistent setting for domains, when you set a custom domain, GitHub inserts a CNAME file in the root of your gh-pages branch with your domain name in it.

When running ignite --deploy, it will publish and remove the CNAME. You can get around this by adding echo domain.com > _ignite/CNAME in your predeploy script, but I think it could be nice to support it automatically via the .igniterc configuration.

What I'm thinking, is maybe if your baseURL contains a full domain, it will automatically strip the root domain and add it to the CNAME file. So a setup like this:

{
  "title": "Ignite",
  "githubURL": "https://github.com/intuit/Ignite",
  "baseURL": "domain.com",
}

would result in domain.com getting written to the CNAME file. It should also still retain the ability to set a root path. So if you were to do

{
  "title": "Ignite",
  "githubURL": "https://github.com/intuit/Ignite",
  "baseURL": "domain.com/ignite",
}

It would write domain.com to the CNAME file and also set the baseURL for the site as ignite.

[Feature request] Tag support

Feature idea

Adding tags (keywords) in frontmatter (meta-data) will generate a page referencing all pages containing this page.

Example:

In frontmatter you add (in YAML for example):

---
tags:
    - dev
    - python
---

So it will create a endpoint http://example.org/tags/dev and http://example.org/tags/python referencing, respectively, all pages containing the dev tag and the python tag.

Then on the page of the documentation where there is such a tags frontmatter, the page will contain some tag link #dev and #python respectively referencing the previously mentioned endpoints.

Example on my blog using Hexo:

Why

Imagine I want to build a hacking documentation with a tree like that (for, let's say, my OSCP exam preparation):

- Admin # Machines from the Admin network, containing a write-up for each machine
  - Machine 1 # tags: [eop,windows]
  - Machine 2 # tags: [network,linux]
  - ...
- Cheat sheets # for various topics
  - Elevation of Privilege # tags: [eop]
  - Metasploit # tags: [exploit]
  - MS SQL Server # tags: [mssql,windows]
  - Network # tags: [network]
  - PWK/OSCP Specific
  - Pivoting # tags: [pivoting,network]
  - ...
- Connectivity
  - Machines
  - PWK Lab
  - Remote desktop
  - ssh-hostkey # tags: [ssh]
- Dev # Machines from the Dev network, containing a write-up for each machine
  - Machine 1
  - Machine 2
  - ...
- Exam
  - Exam specific
  - ...
- IT # Machines from the IT network, containing a write-up for each machine
  - Machine 1
  - Machine 2
  - ...
- Public # Machines from the Public network, containing a write-up for each machine
  - Machine 1
  - Machine 2
  - ...
- Tools
  - Nmap # tags: [network,scanner]
  - John the ripper # tags: [cracking,password,hash]
  - gcc # tags: [compilation,exploit]
  - dnsrecon # tags: [osint,dns]
  - dnsenum # tags: [osint,dns]
  - cmsmap # tags: [cms,web]
  - ncat # tags: [backdoor,network,scanner]
  - recon-ng tags: [osint]
  - snmpwalk # tags: [snmp,network]
  - snmpbrute # tags: [snmp,network]
  - onesixtyone # tags: [snmp,network]
  - ...

So I want to be able to search for a keyword (tag) like snmp and see all machines write-up where I attacked snmp, all cheat sheets explaining snmp stuff, all tools I can use to exploit snmp, etc.

Without tag support this is impossible.

One could say: "But there is already the search feature parsing teh content of pages" yeah but this is automatic and introduce a lot of false positive (content containing a keywork but not really about it) and false negative (content not containing teh keywork but actually talking about it) when the tag feature will be manual so there will be only exact matches.

I could also provide argumentation Why this shouldn't be theme dependent or plugin based. Some big companies liek Docker, Joomla, or the Mozilla foundation are using documentation with tags.

---

By the way as I already love Ignite I added it to alternativeto

Right Side Example view

Something like https://github.com/lord/slate

Automatic Changelog posted to blog

Explore either changelog for docs or associated project

Hide file extensions in url

I noticed that all the routes perform normally when you remove the .html extension, but all the links include the extension. Is there a reason for it? It would for sure be a lot cleaner without them in the url

edit: nevermind, it looked like they were working at first because the docs page was loading, but it was just the index route. Do you have plans to have it work without extensions? This is probably the first react project I've seen that doesn't handle routing that way

Add 'Last Updated' to the bottom of each docs page

Explore refactoring markdown to JSX transformation pipeline

Safari sidebar is off page

JSX character outside code blocks

A string like this:

List<T> 

will get parsed as JSX. To get around this a user can escape the angle bracket characters. This is not the best experience. Ignite should be smart enough to discern between JSX and just plain old brackets.

Might require writing our own markdown-it-jsx plugin. A good chance to clean up the current implementation.

Previous and next button to flip through pages

Could be at the bottom like gitbook https://docs.gitbook.com/

Or on the side of the page

Search sometimes displays blank cards instead of no results.

Expected: When the search is unable to find any matches, no results should be displayed.
Actual: Some queries produce a results page that links to a post but does not show any matched text.
How to Replicate: Open the example page and type why is into the search bar.

Evaluate Windows Compatibility

Does it work? I have never run this on a windows machine.

ignite --watch fails when Chrome isn't running

> ignite --watch

(node:3664) DeprecationWarning: Tapable.apply is deprecated. Call apply on the plugin directly instead
child_process.js:614
    throw err;
    ^

Error: Command failed: ps cax | grep "Google Chrome"
    at checkExecSyncError (child_process.js:574:11)
    at execSync (child_process.js:611:13)
    at Function.listening (/Users/adierkens/Developer/player-rewrite/player/node_modules/ignite/dist/ignite.js:256:41)
    at Nanobus._emit (/Users/adierkens/Developer/player-rewrite/player/node_modules/nanobus/index.js:160:14)
    at Nanobus.emit (/Users/adierkens/Developer/player-rewrite/player/node_modules/nanobus/index.js:26:10)
    at Server.server.once (/Users/adierkens/Developer/player-rewrite/player/node_modules/webpack-serve/lib/server.js:37:11)
    at Object.onceWrapper (events.js:255:19)
    at Server.emit (events.js:165:20)
    at emitListeningNT (net.js:1394:10)
    at process._tickCallback (internal/process/next_tick.js:152:19)
npm ERR! code ELIFECYCLE

Logo doesn't preserve aspect ratio cross-browser

I haven't investigated yet, but I'm guessing that flexbox is used in the header. Flex has some compatibility issues cross-browser, so sometimes things like this happen. I've done pretty extensive work in the past with making flex work cross browser, so I'm gonna have a look at it later and try to get this resolved.

Shown below is the same logo rendered in chrome and epiphany on linux, in firefox it looks fine.

Recent/Related Posts for Individual Blog posts

Should be at the bottom of individual blog post. Might need to add some sort of tagging system or maybe use words present in the blog posts.

Address react console errors

Code Tabs links to index

should just toggle code tab