Proposal Publish Documentation
It should be really easy to take your Markdown files and publish them somewhere.
What sort of publishing?
- GitHub Pages - switch to gh-pages branch, replace content with generated HTML/CSS/JS, commit, push
- Heroku - raw publishing to Heroku
- WebDeploy - allows for syncing of content with an external server - requires config, permissions etc
- FTP - replace content with generated HTML/CSS/JS (requires config, permissions, etc)
- Zip - export the generated content to a specific file
What other platforms are of interest to you?
GitHub Pages
Dependency: git Configuration:
- remote git repository to push code to
- HTTP: username/password permissions to repository (we don’t want this in source control)
- SSH: key (this won’t be in source control either)
So at any point in time you can run:
Publish-GitHubPages
Which will…
- create a temporary clone of the repository (aiming to do just the gh-pages branch)
- overwrite the
gh-pages
branch with the contents of thedocs
folder - change some config values based on how the site will be deployed
- commit and push the changes back to your local clone
- (optional) push the changes straight to GitHub
Heroku
Dependency: git Configuration:
- remote git repository to push code to
- HTTP: username/password permissions to repository (we don’t want this in source control)
- SSH: key (this won’t be in source control either
This could be a simpler workflow than the above:
- take the contents of the docs folder
- commit it to a specific branch (convention: name it
jekyll
) git push heroku jekyll
WebDeploy (MSDeploy)
Dependency: MSDeploy client (licensing question: am I allowed to ship these binaries?)
Configuration:
- remote URL to send content to
- username/password permissions to send files (we don’t want this in source control)
TODO: sketch out API calls which would be necessary to authenitcate and publish folder containing site content
TODO: do we need/want to handle the first-time initialization of a site? is that even possible?
FTP
Dependency: command-line FTP client (no preference, but Windows ships with one)
Configuration:
- remote URL to send content to
- username/password permissions to send files (we don’t want this in source control)