Giter Site home page Giter Site logo

bobclewell / apostrophe-documentation Goto Github PK

View Code? Open in Web Editor NEW

This project forked from apostrophecms/apostrophe-documentation

0.0 1.0 0.0 14.39 MB

Wiki and A2 build for the Apostrophe 2 Documentation site.

License: MIT License

JavaScript 8.84% HTML 30.85% Shell 1.45% CSS 58.86%

apostrophe-documentation's Introduction

Apostrophe Documentation

This project contains the documentation site for Apostrophe.

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

1. Setup

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.

2. Building

To see your work locally, type:

$ ./view

That will compile your site and open it in your browser.

3. Deploying

If you have access, you can deploy your work to apostrophecms.org/docs. Just do:

$ ./deploy

Make sure you commit and push your work of course.

BOOM! ๐Ÿ’ฃ

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

The 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 docs/modules folder:

$ ./generate

./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.

apostrophe-documentation's People

Contributors

alexgleason avatar alohaas avatar austinstarin avatar benirose avatar di avatar fotisp avatar jsumnersmith avatar jth- avatar kyjoya avatar kylestetz avatar mcoppola avatar suhmantha1 avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.