You don't need to read this page just to read the documentation! Read the actual documentation here. This page is about contributing to the documentation.
Building the docs
The static site generator (Habit) is required to generate the docs.
$ npm install -g habit
Clone the repo.
$ git clone https://github.com/punkave/apostrophe-documentation.git $ cd apostrophe-documentation
Now you can run the build scripts.
To see your work locally, type:
That will compile your site and open it in your browser.
If you have access, you can deploy your work to apostrophecms.org/docs. You'll need the
sitemap-static module installed:
npm install -g sitemap-static.
To deploy, run:
Make sure you commit and push your work of course.
How to Contribute
You can work on the nunjucks layouts in
_layouts, write actual HOWTOs in the howtos folder (use markdown and a .md file extension), and contribute LESS in the
stylesheets folder (main.less is what actually gets compiled, everything else should be imported). Any files that aren't markdown or LESS get copied straight to the site, unless they are in a folder starting with
Please note: it's up to you to link to your HOWTOs in the index.md file. We want them in a considered order anyway.
How to Switch Layouts
You'll notice that every page has a title specified as a YAML property at the top. You can add a
layout property there too:
--- title: "Amazing HOWTO" layout: home ---
Note the three dashes, which are required.
Now your page gets rendered with foo.html instead of default.html. I've done this in index.md for instance. Yes, layouts can extend each other and override blocks in the usual Nunjucksian way.
Making links that don't break
For this project if we are hardcoding links in markdown text we go ahead and assume
/ is the home page of the doc site. This won't work with
./view but it will work if you set up a local server and it will work in production.
Regenerating the API docs
docs/modules folder is generated from the Apostrophe source code.
First set up the doc generator app:
# Install the dependencies $ npm install --prefix ./_api-reference-generator/ # Make the data directory $ mkdir -p _api-reference-generator/data
Next, install PhantomJS.
# Install PhantomJS (OSX) $ brew install phantomjs # Install PhantomJS (Ubuntu) $ sudo apt install phantomjs
Now you can regenerate the
./generate ends by running
habit for you. It takes a few seconds because it's doing some fancy things to get information about all of the moog types.
If you need to document a newer version of Apostrophe you will want to
npm update in the reference generator app folder.