apostrophecms / apostrophe-documentation

Documentation for the ApostroheCMS open-souce ecosystem

title
Docs Home

::: note If starting a new project, we recommend using the latest major version, Apostrophe 3. See the A3 documentation for more information. :::

ApostropheCMS Documentation

Tutorials

Our tutorials cover everything you need to know to get started as an Apostrophe developer. Everyone should start here. Our tutorials are progressive, so you can learn as you go. The Getting Started tutorial is a good place to get started.

Getting Started

The "getting started" tutorials are written for developers who are new to Apostrophe. They will walk you through the process of getting your environment set up and creating a basic website.

Core Concepts

The Core Concepts tutorials go through each feature of Apostrophe that you need to understand to build a webite. They will help you get more comfortable with Apostrophe and node.js.

Practical examples of these concepts are illustrated in the Open Musuem project, a fully featured Apostrophe site. You can access the code or try a live demo.

Advanced Development

Advanced Development dives deepers into the features of Apostrophe and the concepts behind it to provide the knowledge and tools you need to build dynamic, responsive sites.

DevOps

DevOps covers all you need to know to deploy and configure Apostrophe for a production environment.

HOWTOs

The HOWTOs cover miscellaneous topics including development, configuration, and customization.

What's the right level for me?

If you're brand new to Apostrophe, go to Getting Started first to learn how to deploy Apostrophe locally for development and testing, and how to create a project. Once you have Apostrophe set up, Core Concepts will help you get a good grasp on Apostrophe's tools. After that, you can dig deeper with Advanced Development or get ready for production with DevOps.

Additional Topics

After you learn the ins and outs of Apostrophe, you'll still have questions, and need more information or references for various Apostrophe components. The remaining sections include the reference and glossary sections.

Module Reference

Our module reference provides complete coverage of Apostrophe's modules and their related object types. Each module provides a particular feature, often including both front and back end code.

Glossary

Working with Apostrophe, there are a lot of a terms and ideas to keep track of. If you need a quick reference or come across an unfamiliar term, check the glossary for a detailed explanation. Read the Glossary

Core Server

The core apos object on the server orchestrates the whole dance. Learn about the core

Core Browser

The browser has an apos object too. tying it all together. Learn about the core

apostrophe-documentation's Issues

Remove .html from URLs

This can be done through most server config and makes for prettier URLs.

Nginx: http://serverfault.com/questions/346994/hide-html-file-extensions-using-nginx-rewrites#346999
Apache: http://stackoverflow.com/questions/1992183/how-to-hide-the-html-extension-with-apache-mod-rewrite#1992191

Not totally related: I love that Harp does this by default. If we can find some magic between Harp and Habit you'd ideally be able to run the Habit server and it would just ignore your .html extensions.

Add page noting the default cookies Apostrophe places

Clients occasionally pop in with GDPR related questions about Apostrophe. I thought one brief and directed page could answer this and show proactivity from Apos on the issue.

From dev tools and some Googling I think this would be limited to:

• shortname.csrf for security purposes
• shortname.sid for login session tracking

Right column on documentation layout doesn't have a scroll

I don't know if here is the right place, but, the contents right column doesn't have a scroll when the window is maximized on computer without touchscreen, in the way that some items are unreachable.

Like this one:
https://docs.apostrophecms.org/apostrophe/modules/apostrophe-pieces

I've tested on three different browsers and noticed that the leftmost colum has a attribute data-scrollable="true" and the rightmost (contents of the page) don't. I couldn't make the right column scrollable just by adding overflow-y: scroll to its CSS, so, maybe it's more complicated.

Use Gitbook extensions to provide better sidebars

Currently we're using Markdown's block quote formatting for warnings, extra info, side notes, etc. Gitbook provides extensions to Markdown to provide a better experience for reading the docs.

Document widget controls removable and moveable

Files API: no return values in formal specification!

This is relevant only when a callback is not the mandatory way the result is delivered.

Use npm scripts for commands

I think it would make sense to have something like npm run generate instead of using a bash script.

Also, adding a package.json with habit as a dependency might make this easier to build.

Broken link in docs

The "You've seen how to add a rich text widget to a page and configure styles and toolbar controls" link is broken.

https://github.com/punkave/apostrophe-documentation/blob/master/docs/tutorials/howtos/ckeditor.md

"Load More" w Ajax confusion

{# Filter by tag. Note this is OUTSIDE data-apos-ajax-page, so it gets REFRESHED #}
<ul class="tag-filters">
  {% for tag in data.piecesFilters.tags %}
    <li><a href="{{ data._url | build({ tags: tag.value }) }}">{{ tag.label }}</a></li>
  {% endfor %}
</ul>

Uncertain where data-apos-ajax-page comes into play. Very likely I'm missing it.. but still a bit confusing.

Also

<a href="{{ data.url }} | build({ page: data.currentPage + 1, append: 1 })">Load More...</a>

I think needs to be...

<a href="{{ data.url | build({ page: data.currentPage + 1, append: 1 }) }}">Load More...</a>

Use heroku's build phase to build production bundle

From March 11. 2019, Heroku will automatically execute build script in package.json.
See https://devcenter.heroku.com/changelog-items/1557.

I managed to use this to minify the assets, so we don't need to do it locally and add the production bundle to git. If you want I can send a pull request to update the docs.

HOWTO on how to debug / improve performance

• using apostrophe-debug
• filters and projections on joins, widget, etc.

Files API: return values in examples!

We don't assign the return values to anything in the examples for files.

Published NPM Modules docs should show more information or guidelines using own dependencies than relying on Apostrophe's Browser libraries pushed (JQuery, Lodash and etc)

I would make a PR for this but I don't know how is it going to be on Apostrophe 3.0 modules. As I recall, Apostrophe 3.x will make everything in VanillaJS on browser side to avoid using Jquery, Lodash and etc. Before making an update to the Docs, I would like to highlight some use case before we proceed to update the docs.

1. As discussed in Discord App regarding of apostrophe lean front-end issue, I believe in Apostrophe 2.x user.js will always push jQuery in it but not in always.js. I hope, we could publish npm package modules from 2.x that also can be used in Apostrophe 3.x to avoid redundancy package published. (It is happening to all modules in Apostrophe 0.5x and this could also avoid confusion on finding the right packaged modules for each version of Apostrophe)

2. If apostrophe lean front-end is enabled, I wonder about $fieldSet attribute in browser-based class module from self.populate arguments. That argument will always return jQuery object which will take different methods to get that querySelector. Main question for this point is , Should we consider If Else statement to determine if the $fieldSet is the constructor of jQuery when using lean front-end and the module is pushed as always ?

In jQuery :

$($fieldSet).find()
// or
$fieldSet.find()

In Javascript :

$fieldSet.get(0).querySelector()

3. Lastly, I would like to highlight on this section of the docs in Apostrophe 2.x Publishing Your Own NPM Modules for Apostrophe, should provide a warning sign without assuming that Apostrophe will always use these dependencies libraries of jQuery, Lodash and etc.

I'm open to more suggestions and ideas on how to fix this documentation issues of publishing our own npm modules to Apostrophe that covers all use cases above.

Heroku Config for AWS S3 and MongoDB

This is my first time submitting and issue, so apologies if I commit any best practice mistakes.

While trying to deploy to Heroku, I followed the documentation on the Apostrophe site, but couldn't get S3 to connect to my app locally or on heroku. While doing research, I discovered that the AWS api looks for env variables named AWS_ACCESS_KEY_ID => xxx and AWS_SECRET_ACCESS_KEY => yyy and S3_BUCKET_NAME=appname-assets. This is also echoed in the Heroku documentation for connecting to S3. Furthermore, the region is not required. Once I update those variables in Heroku, it connected no problem.

Also, similar issue with MongoDB. The apostrophe documentation says heroku config:set 'APOS_MONGODB_URI=mongodb://YOUR-uri-goes-here' but I had to change the env variable to MONGODB_URI for it to work.

Otherwise the CMS is awesome and the documentation has been super helpful. Thank you guys (esp. Tom) for being so responsive to issues and questions.

docker doc error

Hello, there is an error in the documentation for the connection to the mongodb database.
You say : MONGODB_PORT_27017_TCP_ADDR: 'mongodb://mongo'
and

'apostrophe-db': {
      uri: 'mongodb://' + process.env.MONGODB_PORT_27017_TCP_ADDR + ':' + process.env.MONGODB_PORT_27017_TCP_PORT + '/mydb'
    },

But that will produce uri: 'mongodb://mongodb://mongo:2017/mydb'

Possible typo in cursor docs

https://github.com/punkave/apostrophe-documentation/blob/master/docs/tutorials/intermediate/cursors.md#an-illustrated-example

It seems like "we want to fetch the ten most recently updated profiles by authors over 30" maybe should be "we want to fetch the ten most recently updated profiles by reputation over 30" for this example. Is that right?

Doc generator should show inherited methods, options, etc.

Right now you have to follow the "inherits from" link. Or maybe that should just be more prominent?

Document widget controls position option

Support mobile devices

The site isn't responsive and runs into some issues on smaller screen sizes.

I may be the only one, but I actually do read developer documentation on my phone.

Create hierarchy of subtopics in files.md

Home page

The text of the Nunjucks Templates and the Glossary sections are the same.

Improve custom filter example

http://apostrophecms.org/docs/tutorials/intermediate/cursors.html#custom-filters

This example now duplicates a standard filter. We should write a new example that does something you don't get for free. (Copied from "TODO" previously in the docs themselves.)

Test-drive the Heroku HOWTO

http://apostrophecms.org/docs/tutorials/howtos/deploying-apostrophe-in-the-cloud.html

Let me know what's good, what's bad, what's unclear, what's buggy... the target audience is anybody who's built a few Apostrophe sites, so don't feel it's your job to somehow get what I didn't say. Thanks!

Document data.query

Super simple feature that already gives access to req.query in templates, no good if you don't know about it...

Arranging fields - erroneous instruction ?

Hi!

I'm currently following the (pretty awesome!) getting started guide, and when following the instructions on arranging the fields, the only way I'm able to change the name of the "Basics"-tab to "Administrative" is by providing name: 'basics' instead of name: 'admin'.

If this is intended, I guess the docs should be updated to reflect the correct name value :)

Document all template helpers in a "cheat sheet"

I want to preface my small complaint by saying that the Apostrophe docs are some of the best technical docs I've ever seen. Well written, widely encompassing and well maintained. But there's always room for improvement!

Template helpers in Apostrophe have sometimes confused me a little bit. The fact that they are all namespaced under the apos variable initially lead me to believe that I was interfacing directly with the main apostrophe instance. Once you realise that's not the case, there's still no way of easily inspecting that object (you can't console.log it and you can serialize it to JSON). The module reference documentation does contain details on which template helpers the different modules register, but there's no central reference of which template helpers that the apos object contains.

It would be very helpful to have a central reference like that, a "cheat sheet" if you will. This would also make it easier to not have to look up the aliases of the different modules - ie. areas in apos.areas.richText()

Document apos-attachments disabledFileKey option.

apostrophecms/apostrophe-redirects#10 (comment)

Quoth Tom:

There is now a practical path to fix this:

1. npm update

'apostrophe-attachments': {
  uploadfs: {
    disabledFileKey: 'very-random-string-please-not-this'
  }
}

3. Deploy as usual. (Please note: I put these steps in this order for reasons)

4. On the server, run this task to complete the transition:

   node app apostrophe-attachments:migrate-to-disabled-file-key

Now files in the trash have their names changed rather than their permissions changed. Recommend verifying an example.

BENEFITS

• You can now sync down without permissions nonsense! Woo
• You can now create a redirect for the old URL of the file, because the file ain't there no more.

No docs on custom image sizes for Apostrophe 2.0

It seems that the old documentation on adding image sizes and regenerating images with the CLI still applies more or less directly. However, there isn't a tutorial around these concepts in the latest documentation, even though the "Adding editable content to pages" chapter does say

We'll talk about custom image sizes in a later tutorial.

Maybe you're aware of this already, but especially seeing as it's such a compelling feature, I thought I'd bring it up.

Broken self pattern link in the technical overview

The justjs website is no more and the link (http://justjs.com/posts/this-considered-harmful) is therefore broken on the technical overview page under Apostrophe's module pattern, inheritance, and moog section.

Cleanup unnecessary files

We can remove a ton of stuff now that we're not responsible for rendering a website

Switch repos from dummy to this one

Broken links into the documentation

Hi, I've found some broken links into the documentation like the links of this part of the documentation.

https://docs.apostrophecms.org/apostrophe/tutorials/intermediate/forms#displaying-and-submitting-the-form-contact-form-widgets

New generation of `modules/` overwrite module reference overview

The leading link in the Modules heading of SUMMARY.md should go to an overview of the module reference .. that file keeps being overwritten by the generation

original file we want is here https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/legacy-final/modules/index.md

should be named README.md

Add reference to prominent sites using Apostrophe

Internal discussion indicates it's worth now adding a section on the site (e.g., homepage) to list showcase sites using Apostrophe.

extend/extends typo in "Reusable content with pieces" doc

Some sections of "Reusable content with pieces" page contain typos in nunjuck tempates with the extends keyword

https://docs.apostrophecms.org/apostrophe/tutorials/getting-started/reusable-content-with-pieces#using-ajax-to-enhance-filters
https://docs.apostrophecms.org/apostrophe/tutorials/getting-started/reusable-content-with-pieces#combining-a-load-more-button-with-ajax

Doc generator should show "inherits from" for more related types and browser types

Currently only works for modules.

Enable SSL

Now that Let's Encrypt exists we can basically throw SSL certs at EVERYTHING! Why a static site though? I think it gives users the impression of legitimacy and maybe a little peace of mind. I've noticed there's also an Apostrophe Forum where users log in with passwords, so that would definitely benefit from SSL.

Tbh I'm not entirely sure how to use Let's Encrypt on my own. I've been spoiled by Dokku, which lets me literally run one command to enable SSL on any of my websites.

$ dokku letsencrypt myapp

It's amazing. Works every time without hassle and enables HTTPS instantly. My mind is blown.

Point is though, once you figure it out it can be automated and applied at an instant. Maybe this is also something to look into for stagecoach?

extensions/extension option typo in files doc

Style lists

Lists are nice

Google custom search results obscured by main nav

When using the Google custom search functionality for the docs, the main navigation menu on the left overlays the results and obscures the page titles. Tested in both FF and Chrome. See attached image:

Merge `gitbook` into `master`

Attachments methods need brief description

Several methods for apos.attachments don't have any explanation. I was particularly trying to use crop and not sure if it was meant to do what I was trying to do.

https://github.com/punkave/apostrophe-documentation/blob/master/modules/apostrophe-attachments/index.md

Generator should support Gitbook flavored SUMMARY.MD

# Table of contents

* [ApostropheCMS is a rapid website framework written in Node.js](README.md)

## Tutorial Sets

* [Getting Started](tutorial-sets/getting-started/README.md)
  * [Setting up your environment](tutorial-sets/getting-started/setting-up-your-environment.md)
  * [Creating your first project](tutorial-sets/getting-started/creating-your-first-project.md)
  * [Editing page templates](tutorial-sets/getting-started/editing-page-templates.md)
  * [Adding editable content to pages](tutorial-sets/getting-started/adding-editable-content-to-pages.md)
  * [The global doc: sharing content across pages](tutorial-sets/getting-started/global.md)
  * [Pushing assets to the browser](tutorial-sets/getting-started/pushing-assets.md)
  * [Building Navigation](tutorial-sets/getting-started/building-navigation.md)
  * [Custom widgets](tutorial-sets/getting-started/custom-widgets.md)
  * [Layout / Nested widgets](tutorial-sets/getting-started/layout-widgets.md)
  * [Reusable content with pieces](tutorial-sets/getting-started/reusable-content-with-pieces.md)
  * [Global Settings](tutorial-sets/getting-started/global-settings.md)
  * [Guide to schemas](tutorial-sets/getting-started/schema-guide.md)
* [Intermediate Tutorials](tutorial-sets/intermediate-tutorials/README.md)
  * [Managing your permissions](tutorial-sets/intermediate-tutorials/permissions.md)
  * [Custom schema fields for pages](tutorial-sets/intermediate-tutorials/custom-schema-fields-for-pages.md)
  * [Apostrophe's model layer: working with the database](tutorial-sets/intermediate-tutorials/model-layer.md)
  * [Working with cursors](tutorial-sets/intermediate-tutorials/cursors.md)
  * [Building a contact form](tutorial-sets/intermediate-tutorials/forms.md)
  * [Command line tasks](tutorial-sets/intermediate-tutorials/command-line-tasks.md)
  * [Accessing the database directly](tutorial-sets/intermediate-tutorials/accessing-the-database-directly.md)
  * [Custom schema field types](tutorial-sets/intermediate-tutorials/custom-schema-field-types.md)
  * [Hosting Apostrophe in production](tutorial-sets/intermediate-tutorials/deployment.md)
* [HOWTOs](tutorial-sets/howtos/README.md)
  * [How do I create a 404 Not Found page?](tutorial-sets/howtos/notfoundpage.md)

## Technical Documentation

* [Technical overview: 30,000 feet](technical-documentation/technical-overview.md)
* [How Apostrophe starts up](technical-documentation/how-apostrophe-starts-up.md)
* [How Apostrophe handles requests](technical-documentation/how-apostrophe-handles-requests.md)
* [How Apostrophe modules are structured](technical-documentation/how-apostrophe-modules-are-structured.md)

## More

* [Modules](more/index/README.md)
  * [apostrophe-admin-bar](more/index/index/README.md)
    * [Browser](more/index/index/browser.md)
  * [apostrophe-any-page-manager](more/index/index-1/README.md)
    * [Server](more/index/index-1/server/README.md)
      * [apostrophe-any-page-manager-cursor](more/index/index-1/server/server-apostrophe-any-page-manager-cursor.md)
    * [Browser](more/index/index-1/browser/README.md)
      * [apostrophe-any-page-manager-chooser](more/index/index-1/browser/browser-apostrophe-any-page-manager-chooser.md)
      * [apostrophe-any-page-manager-relationship](more/index/index-1/browser/browser-apostrophe-any-page-manager-relationship-editor.md)
      * [apostrophe-any-page-manager](more/index/index-1/browser/browser-apostrophe-any-page-manager.md)
* [Promise Events](more/events.md)
* [Nunjucks Filters](more/nunjucks-filters.md)
* [Glossary](more/glossary.md)
* [More on Modules](more/more-modules.md)
* [Core Browser](more/core-browser.md)
* [Core Server](more/core-server.md)

Use examples with full options

All internal links are broken

All the internal lnks are broken - for example go to https://docs.apostrophecms.org/apostrophe/modules/apostrophe-doc-type-manager and click on the link to apostrophe-module at the top of the page.

Many (all?) of the other links in the pages are broken too, the only ones that work properly seem to be those created by gitbook.

Named anchors below level h3 should be preceded by the anchor for their h3

"strong" is underwhelming even with "font-weight: bold"

See:

https://dl.dropboxusercontent.com/spa/jfyjetktfp495r1/fvh2y20n.png

I added "font-weight: bold" for "strong" tags, but it's still not very empha-tastic.

cc @stuartromanek

Fix internal links

When moving to gitbook, internal documentation links must point to the relative .md file instead of the generated html file

SVGS / PNGs should have width/height props

Document how to configure client-side slideshow options

It'd be helpful to have handy docs for turning off autoPlay and changing the delay time in core slideshows.