Make it simpler to set up a new project.
- Dominant language
- JavaScript
- Stars
- 598
- Forks
- 371
- PR merge metrics
- No merged PRs in 30d
Description
Here are a few ideas I have to make it simpler for developers who are new to DocumentJS to get up and running in no time flat:
## Use README.md as the default home page
Using README.me as the default home page should work well since most repositories use the README as a general overview of the repo's contents.
To make this work, the `home` site could contain a default configuration similar to this:
``` js
{
"sites": {
// This section could be left out and it would still use these as defaults
"home": {
"glob": "README.md",
"dest": "."
}
}
}
```
For multi-repo, versioned configurations, the default would be to include the README.md from the root of each imported repo. This would allow for switching versions of the home page, but would use the `defaultVersion` as the root index.html. Other versions would be in the respective version's folder.
``` js
{
"versions": {
"0.1": "git://github.com/marshallswain/amityapp#version0.1",
"0.2": "git://github.com/marshallswain/amityapp#master"
},
"defaultVersion" : "0.2",
"sites": {
// This section could be left out and it would still use these as defaults
"home": {
"glob": "0.2/README.md",
"dest": "."
}
}
}
```
In the above example if a "home" site is specified in the local (say, `gh-pages`) documentjs.json config, it will take precedence over the defaultVersion's `home` config. The home page for the defaultVersion would then be put into the `0.2` folder in the above example, and the custom page would become the root index.html.
This is an example of what the default home page would look like pulling in a vanilla README.md file;

We would probably want to hide the sidebar by default (unless there is specific DocumentJS markup on the page that would split the contents of the home page into multiple pages). Or, as an alternative, we could have the table of contents show in the left sidebar and maybe even give it [scrollSpy-like](http://getbootstrap.com/javascript/#scrollspy) behavior. If the sidebar is hidden, and multiple versions are specified in the config, then the version selector would need to be rendered in another location, since it's currently in the sidebar.
The first `h1` element should also be shifted from the page content to be used as the `@title` tag, so the home page will better match the generated docs on other pages:

Having the README.md as the default home page would make starting a basic docs site simpler. We could then create a guide on how to create a custom home page (by overriding the defaults) and to use the README.md as the home page for the API page.
## Make branding customization simpler #162
## Build the main nav from the config #163
## Integrate into the Guides
The guides could be updated to show the quickest way to get a new project up and running with the above changes. We could then do a guide on how to add a `site` to the config and have it show up in the menu, then another guide on how to add a page to that site.
## Final Comments
Making the above changes would be huge for the two biggest use cases:
1. Those who want to build from `gh-pages` or another location. These are probably the ones who want to make a full-blown custom site with demo apps and a vanity home page. Using a second branch would keep their master branch's code separate from all of the templates, homepage files, and styles, etc.
2. Those who want to build from `master`. This would mostly be developers who want to get the API docs, but aren't concerned with the rest of the home page. They could simply clone master and run documentjs in the project root to get what they're after.
I don't think any of the above additions/changes would conflict with or limit the current DocumentJS API. Maybe somebody with more experience could think of improvements to what I've brought up here.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.