orchidhq / orchid Goto Github PK

Move Index generation and site search to a new plugin. This includes the current IndexGenerator, which creates the generator-specific sub-indices as well as the root index, but also the creation of a new generator that creates a .json file to accompany each indexed page that can be loaded more selectively.

This also allows us to move the Javascript for Lunr.js and OrchidSearch out of core, and should be added to pages as an asset-only component. Themes will still be expected to implement their own search interface that works well within their own theme, but there can be an additional, generic searchbar component that can be used in themes that don' natively support search.

Add a component that handles return data from a server of a specific format, to be included on the generated submission pages. It should use Javascript to show the data submitted, and also show errors if it was wrong, along with a link back to the original form.

May want to include this in the Page base class

Encapsulate Component styling. Add Flag to enable/disable shadow DOM. When shadow DOM is disabled, wrap all component styling in a selector created for that individual component, and render those assets as SCSS. Alternatively, use Polymer/polyfills to support Shadow DOM in older browsers as well

Assets are typically binary or non-content files that ar not useful to include in the index. They should be included in a Collection, but not the index. This will also keep assets out of sitemaps and meta/index files, which is also desired.

Set a timeout on the file watcher updates so that a build only happens once per edit. The build process itself should not allow another build to be queued while one is currently running, instead it should just drop the job.

Add an Options Extractor that references an item/items in another Collection. These must be lazily-loaded, just like Menus and Components, as not all generators have finished indexing by the time they are referenced, and should allow one to refer to an item in a Collection by a String ID. Requires some pretty significant refactoring of how Pages and Collections are built/indexed:

• Pages need to have a collection-local unique ID. The ID for this Page should be the same, regardless of which Collection it is in. We can lookup any single Page by referring to the ID within a Collection, or just by ID, thereby searching in any collection.
• OrchidCollection should be made abstract, and the Annotation references a specific Collection class, or none at all (meaning it just links to an arbitrary Page). For example, Posts can link to pages in the Author collection, and contain a featured image from the Assets collection, but may have "related pages" coming from any collection.
• Generators may return multiple instances of the same Collection class, as long as each one has a unique string key. Lookups targeting a collection are then required to target the collection type and the collection key. The Type is implicit if the annotation specifies the class, otherwise it should be explicit.
• Implementations of the Collection are free to perform whatever kind of lookup they need based on what they have been given. The default will be searching all Pages according to their output path.
• Relation options should typically only be set on front-end objects: Pages, Menus, Components, and TemplateTags, but not Services, Generators, etc.
• The Relation option type should intrinsically support both one or many related objects, and contain APIs that make it simple to work with either. Internally, it will all be managed as if it were multiple objects, but just contain convenience methods for treating it as a single object. (Being managed as an OptionExtract means we could open this up to arrays, but for now it will just support single-references)
• These Relations can then transparently be reflected within the NetlifyCMS, as we manage internal references very similar to how NetlifyCMS does (NetlifyCMS does not currently support a model that directly translates to Orchid's relations, as Orchid often generates titles and can match on generated titles, while NetlifyCMS cannot)

Allow Javadoc plugin to be run when there is no source. At least for the time being, this will allow Orchid to still be run on all the kotlin subprojects, since there are still "sources", but they are all in resources and not in Java source files

The documentation must be complete before Orchid is ready for public release. Specifically:

• Finish User Manual wiki entries
  • Set each page to a Template (extends a base template, and overrides all blocks)
  • Ensure each page is fully written and content style is consistent across all pages
  • Ensure each page has examples and screenshots, if necessary
• (maybe) Add a set of video tutorials on Youtube, demonstrating basic usage and customization
  • One video for using Orchid from the Starter Repo. Include getting set up with Netlify button and the Netlify CMS, and also running locally
  • One video for integrating Orchid into an existing Gradle project (use Clog as the example)
  • One video showing how to build custom versions for each of the following Orchid parts: Components, Tags, Functions, Menus, Generators
• Finish the sub-documentation sites for every official plugin
  • Make sure each one has a unique color, name, and short description
  • Ensure each plugins site clearly demonstrates basic usage of that plugin
  • Ensure each site shows its custom classes' options, and that each option has a description
• Finish the sub-documentation sites for every official theme
  • Give each Theme site identical content, and differ as little as possible in configuration
  • Ensure each site shows its theme's options, and that each option has a description

This would allow us to download a single file via AJAX and show all available versions of the project from all archived versions of the docs.

Currently, datafiles simply overwrite the corresponding keys in the parent-level map. Instead, deep-merge datafiles options into the full site config, appending arrays and combining map keys, rather than overwriting.

We than then ensure certain methods are only called when they data they need is set up. For example, never allow ComponentHolders or Menus to set up their inner members before indexing is complete. This would be controlled via AOP and Guice annotations for simplicity, and so that we don't have anything that is tightly enforcing these rules.

In a similar manner to how we add a Gradle check to OrchidCore for release notes, add a check to each plugin, bundle, and theme project to ensure they all have pages represented in the OrchidCore Orchid site. Possible allow others to list unofficial plugins in the same pages, but we must always have the official plugins and themes with their own pages.

Currently, Components are only rendered sequentially on the page, and they can only be set up in the page's configs. This is great, and should be the preferred method of rendering components. However, we should be able to declare and render Components within the actual page template or in the pre-compiler step of the page content as well, in a manner similar to OctoberCMS components.

There are two situations when rendering components like this:

1. The Component has already been declared in the normal Page components. In this case, we should "inherit" that component and remove it from the remaining page components, so it gets rendered where we want it to in the template instead of in the component list. Options primarily come from the Front Matter or Archetype, but may be overridden by passing them to the component tag. For Components that should be displayed after the remaining page components list, we must have a way of designating that component to not be rendered in the list.
2. The Component has not been declared in the page components list. Here, we find the component as if it is a Component Holder, passing in the options to be extracted. We cannot add scripts or styles at this point, since they may have already been rendered, but we can still render the component template.

Along with this, create a Presentation layout that displays the presentation full-screen and is not based on the current theme. Of course, the Theme may provide their own Presentation layout if they desire.

The themes tend to lag behind the plugin development progress, and they need to be brought back up-to-speed.

All Themes

• Ensure they all use the appropriate templates in every situation. Make sure every template from each plugin is overridden in at least one theme, to demonstrate how template overriding works.
• Make sure everything that now has a link, like Post authors, actually goes to that link.
• Clean up styling where appropriate, especially when it is related to syntax highlighting and page content styling.

Add a concept of "Post Series" to the Posts plugins This should:

1. Allow posts to assign themselves to a Series, and optionally give themselves an order within the series.
2. Change the Post's default "next" and "previous" links to navigate the series instead of the category.
3. Add a Component that displays a table with the post series Table of Contents, highlighting which post in the series is currently being viewed. If the Component is used on a Post with a Series, it forcibly adopts that Post's series to display, otherwise the Series can be added as a component to another page and must specify the series to display.
4. Post Series can be cross-category, like tags. Unlike tags, no archives are generated for series, and a post can only belong to a single series. Unlike Categories, Series should not be hierarchical.

Feed Options

• Set how many items to include in a Feed
• Set whether to use Atom, RSS, or both (default: both)

Allow components to declare how many components of that type are allowable on a page. Practically speaking, this would be limited to how many are declared in a single ComponentHolder

Form component should optionally inject a Javascript snippet to submit the form via AJAX rather than the normal HTTP form submission On submission, the form is replaced by either a generic message (if the Form doesn't have a submission page), or else the content of the Submission page.

Also see about handling return data from a server of a specific format, to be included on the generated submission pages. It should use Javascript to show the data submitted, and also show errors if it was wrong, along with a link back to the original form.

Allow categories to be described as a tree, instead of a flat list. Category archives then include all pages from the posts in its own category and all its child categories, recursively. This should go to the very root of the blog, which includes every blog post in every category.

Setup the Sitemap as an index sitemap, where each sub-sitemap is the sitemap from each Generator. https://www.sitemaps.org/protocol.html

Include the sitemap in the robots.txt file.

Remove the archive pages functionality from the Posts plugin, and instead rely wholly on the the Taxonomies plugin to implement the archive pages feature. This will help keep these plugins focused while also encouraging users to use multiple plugins, and only those that they really want.

Posts should be able to be set as a collaboration between several Authors. Any number of Authors may be added to a Post, but only a single one can be the Primary Author. If there is only one Author for a post, they are automatically the Primary Author.

By default, Authors are just the short description in the generator options. Author Pages should come from a file in posts/authors (configurable) with arbitrary content, and Authors with a page can provide a link to this page. Only Authors that are specified in the Generator options or in the Author pages will have Pages generated; Authors defined on the post are said to be "guest authors".

Within IndexGenerator, for every page, generate an accompanying .json file containing that page's content, so that Orchid sites could potentially have their content loaded quickly within mobile apps without necessarily needing a full webview and all related assets.

Need to research support for various popular frameworks. Might include an option to choose your framework, and the "spoofing" mechanism is tailored to that application. Would likely be very hard-coded.

Catch all exceptions thrown from generator startIndexing and startGenerating callbacks. Also add an event that can be fired anywhere notifying of an error. These errors should be collected and then displayed in bulk after the build process, after displaying the build statistics, so users can clearly see what needs to be fixed.

It is currently hard-coded to add site, theme, config, and index into every page. Instead, we should pull these objects from a Guice-injected set of "global object factories", which also allows other plugins to add their own global variables.

Tags

• Gist
• Highlight
• Instagram
• Twitter
• Youtube
• figure
• Vimeo

Filters

Create a new plugin that adds Netlify CMS to an Orchid site. It should:

• Generate the required admin/index.html and admin/config.yml files:
  • Setup interfaces so that other plugins can add their content models to Netlify CMS "collections"
  • Generate the fields necessary for each page type based on their declared Options
  • Register Widgets for all Orchid Component types
  • Register EditorComponents for all Orchid TemplateTag types
• Set itself up with API endpoints that implement the Filesystem backend, so the CMS can be used in development as well as in production

Make dedicated AssetPage, CssPage, and JsPage classes to provide additional functionality to adding CSS and JS, such as wrapping CSS in an extra selector or combining multiple resources into one bundle. JS assets should be able to set whether they are a head or body script, and also set things like "async"

Set up Providers for certain core, injectable classes. Then instead of binding the class to the implementation, we inject the set and force possible choices and pick the one with the highest priority, or pick one based on a Flag. This way, other plugins would have a way to replace core functionality, and users would also be able to make these choices for themselves if they desire. An example would be replacing the FileRenderer with one that uploads directly to a CDN

Currently, drafts are set only by the boolean property on OrchidPage. This would allow drafts to be changed dynamically based on date. In a site that is continuously generated, it would allow pages to be written with a future publish date in mind, knowing that on that date the Page will automatically no longer be a draft. Likewise, we can set up pages with a limited lifespan, knowing they will be hidden after a specific date.

Add Gradle plugin to run Orchid from Kotlin's "Javadoc" Dokka. May need to reach out to the Dokka team to find the simplest way to integrate Dokka and Orchid, hopefully without re-inventing their build tool.

Currently all post categories use the same configs which are set on the generator. Configs should be moved to the category model and used from there, in the same way that taxonomies are configured, so that each category can have its own permalink, pagination, template, etc.

Currently, we only support finding resources one-at-a-time or by directory. Directory search can be recursive and can filter by file extension, but we should also allow lookups by a glob pattern. This would be useful in situations such as nested post categories, allowing each category to exclude the subtrees for its inner categories.

This could be implemented as another callback in the ResourceSource class. By default, it would find out the topmost directory to search, then match each file in that individually to the glob pattern. For the File resource source, we can use the Java nio glob search functionality for performance optimization. Alternatively, we could just skip over resource sources that do not support glob searches, leaving just file searches for globs.

Have Orchid install a SecurityManager implementation that enforces reads and writes to the filesystem. Ensure that we only read from a certain directory and deeper (which should default to the project root directory, set in the gradle task), and only write to or delete from the output directory or system temporary directories.

Gradle plugins (in buildSrc) should include:

• The core plugin to run Orchid from command line
• Plugin to run Orchid from Javadoc
• Additional plugins for other purposes, such as Dokka (Kotlin), Scaladoc, etc. Integrating Orchid with those tools should have an accompanying Orchid Plugin which implements the same or similar functionality as the Gradle tool it is replacing, but embedded within Orchid.

Each plugin should be distributed as its own plugin on the Gradle Plugins Portal. All "additional" plugins should either require the core plugin or have the core plugin bundled with it.

Also, add Gradle plugin to run Orchid from Kotlin's "Javadoc" Dokka. May need to reach out to the Dokka team to find the simplest way to integrate Dokka and Orchid, hopefully without re-inventing their build tool.

Subtasks

• Move Javadoc to separate plugin
• Create Dokka plugin (even if it just replaces the Dokka task without generating code docs at the moment)
• Create Android-based Orchid plugin (rather than java-based)
• Create Android-based Javadoc plugin (rather than java-based)
• Create Maven Orchid plugin
• Create Maven Javadoc plugin

The templates for the Javadoc plugin need to be fully implemented.

Outstanding tasks

Classdoc

• Display Summary
• Display Fields
• Display Constructors
• Display Methods
• Add return types to method signatures and body docs
• For anything that shows a class, render the class entirely custom, including all type parameters. Annotations on method and field arguments should only be shown in the full descriptions of the parameters.
• Anytime a class is referenced at all, make it a link. First check local javadoc pages, then external pages, then fall back to the official Java documentation (to capture the standard JDK classes and make them all linkable).
• Render all annotations with their params
• Generate unique IDs for every element on the page. Each field, constructor, and method should be able to have ID links to them, and have a guarantee that they will never collide.
• Get list of known subclasses. This takes into account both internal classes and external pages. Include both direct and indirect subclasses (typically, only direct subclasses can be known from external docs).

Packagedoc

• Link to all of a packages own classes and to its sub-packages. Show a short description of each class and child packages, if it exists.
• Group the classes by type: interface, class, enum, exception, error, and annotation.

Other

• The basic Javadoc templates use Bootstrap. Provide a lightweight stylesheet that is not bootstrap, doesn't interfere with Bootstrap, and only targets the javadoc pages, but that makes the Javadoc presentable in any theme. It's not bad as it is, but without the structure provided by Bootstrap panels, it can be a bit difficult to really navigate. It is not added by default, so it is expected that themes either use the bootstrap styling or include this stylesheet.
• Make it possible to link to Javadoc pages from other sites when linking to classes. These pages should come from the Orchid "external" index, and not be required to have come from the Javadoc plugin. For example, we could link to a Kotlin class from the Javadoc tool when we get Kotlin docs set up

This plugin should search the entire Index and group pages into custom taxonomies, in a manner similar to Hugo. Content should not be restricted to any single generator, and is read generically from Front Matter, so can work with any Page type, and also takes Archetypes into account, making it easy to apply taxonomies to a wide range of pages without needing to maintain it on each.

This would effectively replace blog Tags (but perhaps still keep Categories, as they will eventually be hierarchical and are managed by directory), and would eliminate the need for Post Series as a special thing in the Posts plugin. I may want to remove generated Post archives, in lieu of Taxonomy pages that target the Categories.

Internally, Taxonomies are a late-running Generator, which reads all currently-indexed pages for taxonomies, building paginated archives for them all, as well as landing pages for the taxonomies showing the different taxonomy type and the terms under it. Taxonomies can each define permalinks for generated pages, and also decide whether a page can have multiple terms for a single taxonomy. Taxonomies also generate Collections of related pages.

Plugin Features

• Implement a Generator that categorizes Pages from other generators into Taxonomies, Terms, and Pages in the same manner as Hugo
• Generate archive pages for all the Terms in each Taxonomy
• Generate archive pages for all the Pages in a given Term within a Taxonomy
• Create a Component that displays all the Terms in a given Taxonomy. Add this by default to Taxonomy pages
• Create a Component that displays all the Pages in a given Term within a Taxonomy. Add this by default to Term pages
• Create a Menu Item that shows all available Taxonomies
• Create a Menu Item that shows all the Terms in each Taxonomy
• Create a Menu Item that shows all the Pages in a given Term within a Taxonomy

Taxonomy Configuration Options

• Only look at Pages from a specific set of Generators
• Exclude Pages from a specific set of Generators
• Set the permalink for the Term and Taxonomy archive pages
• Set the number of items per archive page
• Set the ordering of terms. Accept a list of terms in the order they should be used
• Set the ordering of Pages. Accept a list of properties, pages are sorted by these properties in that order
• Set the display title