diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index aed9cbad8..000000000 --- a/INSTALL.md +++ /dev/null @@ -1,275 +0,0 @@ -## Contents - -- [Installation](#installation) - install the application on a machine - - [Via Docker](#installation-from-docker) - - [Via Source](#installation-from-source) -- [Setup](#setup) - setup the application for first use -- [Usage](#usage) - connect the application to a website - -# Installation - -## Requirements - -- Any flavour of Linux, OSX or Windows -- 1GB memory (minimum) -- 5GB storage (minimum) -- [MongoDB](https://www.mongodb.com/) v3.4 or later -- [Redis](https://redis.io/) v3.2 or later -- SSL Certificate - - This application assumes that you will be serving this application in a - production environment, and therefore requires that you serve it behind a - webserver with a valid SSL certificate. This is chosen in order to secure - user's sessions. - -## Installation From Docker - -We currently support packaging the Talk application via Docker, which automates -the dependency install and asset build process. This is the recommended way to -deploy the application when used in production. - -Available as [coralproject/talk](https://hub.docker.com/r/coralproject/talk/) on Docker Hub. - -Images are tagged using the following notation: - -- `x` (where `x` is the major version number): any minor or patch updates will be included in this. If you're ok getting - new features occasionally and all the bug fixes, this is the tag for you. -- `x.y` (where `y` is the minor version number): any patch updates will be - included with this tag. If you like getting fixes and having features change - only when you want, this is the tag for you. **(recommended)** -- `x.y.z` (where `z` is the patch version): this tag never gets updated, and - essentially freezes your version, this should only be used when you are either - extending Talk or are sure of a specific version you want to freeze. - -We provide tags with `*-onbuild` that can be used for easy plugin integration and -acts as a customization endpoint. Instructions are provided in the `PLUGINS.md` -document as to how to use it. - -### Requirements - -There are some runtime requirements for running Talk for Docker: - -- [Docker](https://www.docker.com/) v1.13.0 or later -- [Docker Compose](https://docs.docker.com/compose/) v1.10.0 or later - -_Please be sure to check the versions of these requirements. Incorrect versions -of these may lead to unexpected errors!_ - -### Installing - -An example docker-compose.yml: - -```yaml -version: '2' -services: - talk: - image: coralproject/talk:1.5 - restart: always - ports: - - "5000:5000" - depends_on: - - mongo - - redis - environment: - - TALK_MONGO_URL=mongodb://mongo/talk - - TALK_REDIS_URL=redis://redis - mongo: - image: mongo:3.2 - restart: always - volumes: - - mongo:/data/db - redis: - image: redis:3.2 - restart: always - volumes: - - redis:/data -volumes: - mongo: - external: false - redis: - external: false -``` - -At this stage, you should refer to the `README.md` for configuration variables -that are specific to your installation. Some pre-defined fields have been filled -in the above example which are consistent with Docker Compose naming conventions -for [Docker Links](https://docs.docker.com/compose/networking/#links). - -### Scaling - -If you are interested in splitting apart services, you can simply adjust the -command being executed in the container to optimize for your use case. An -example would be if you wanted to run the API server and the job processor -on different machines. You can achieve this easily with docker compose: - -```yaml -version: '2' -services: - talk-api: - image: coralproject/talk:1.5 - command: cli serve - restart: always - ports: - - "5000:5000" - depends_on: - - mongo - - redis - environment: - - TALK_MONGO_URL=mongodb://mongo/talk - - TALK_REDIS_URL=redis://redis - talk-jobs: - image: coralproject/talk:1.5 - command: cli jobs process - restart: always - ports: - - "5001:5000" - depends_on: - - mongo - - redis - environment: - - TALK_MONGO_URL=mongodb://mongo/talk - - TALK_REDIS_URL=redis://redis - mongo: - image: mongo:3.2 - restart: always - volumes: - - mongo:/data/db - redis: - image: redis:3.2 - restart: always - volumes: - - redis:/data -volumes: - mongo: - external: false - redis: - external: false -``` - -Note that the only difference is in the `command` key. From this, you are able -to discretely control which modules are running in order to have the maximum -flexibility when managing your application. - -### Running - -If you're using docker compose: - -```bash -# Start the services using compose -docker-compose up -d -``` - -If you're using plain docker: - -```bash -docker run -d -P coralproject/talk:latest -``` - -## Installation From Source - -This provides information on how to setup the application from source. Note that -this is not recommended for production deploys, but will work for development -and testing purposes. - -### Requirements - -There are some runtime requirements for running Talk from source: - -- [Node](https://nodejs.org/) ~7.8 -- [Yarn](https://yarnpkg.com/) ^0.22.0 - -_Please be sure to check the versions of these requirements. Incorrect versions -of these may lead to unexpected errors!_ - -### Installing - -#### Download - -It is highly recommended that you download a released version as the code -available in `master` may not be stable. You can download the latest release -from the [releases page](https://github.com/coralproject/talk/releases). - -You can also clone the git repository via: - -```bash -git clone https://github.com/coralproject/talk.git -``` - -#### Building - -We now have to install the dependencies and build the static assets. - -```bash -# Install package dependancies -yarn - -# Build static files -yarn build -``` - -After you create/modify the `plugins.json` (refer to `PLUGINS.md` for plugin -docs) file, you can re-run the following to install their dependencies: - -```bash -# Reconcile plugins -./bin/cli plugins reconcile - -# Build static files -yarn build -``` - -### Running - -Refer to the `README.md` file for required configuration variables to add to the -environment. - -You can start the server after configuring the server using the command: - -```bash -yarn start -``` - -This will setup the server to serve everything on a single node.js process and -is designed to be used in production. - -You can see other scripts we've made available by consulting the `package.json` -file under the `scripts` key including: - -- `yarn test` run unit tests -- `yarn e2e` run end to end tests -- `yarn build-watch` watch for changes to client files and build static assets -- `yarn dev-start` watch for changes to server files and reload the server while - also sourcing a `.env` file in your local directory for configuration - -# Setup - -Once you've installed Talk (either via Docker or source), you still need to -setup the application. If you are unfamiliar with any terminology used in the -setup process, refer to the `TERMINOLOGY.md` document. - -## Via Web - -If you want to perform your setup via the web, you can navigate to your -installation of Talk at the path `/admin/install`. There you will be asked a -series of questions for your installation. - -## Via CLI - -If you want to perform your setup through the terminal, you can simply run: - -```bash -cli setup -``` - -And follow the instructions to perform initial setup and create your first user -account. - - -# Usage - -After setup is complete, you can then refer to the `/admin/configure` path to -get the embed code that you can copy/paste onto your blog or website in order to -start using Talk. - -_In order for the embed to work correctly, you will need to whitelist the domain -that is allowed to embed your site on the `/admin/configure` page, failure to do -so will result in the comment stream not loading._ diff --git a/PLUGINS.md b/PLUGINS.md deleted file mode 100644 index ac34240b1..000000000 --- a/PLUGINS.md +++ /dev/null @@ -1,3 +0,0 @@ -# Talk Plugins - -Our documentation for Talk has moved! Utilize [this hyperlink](https://coralproject.github.io/talk/plugins.html) via click or tap to navigate your browser to the new location! diff --git a/README.md b/README.md index 86e8000d0..89aaefee8 100644 --- a/README.md +++ b/README.md @@ -5,106 +5,9 @@ Online comments are broken. Our open-source Talk tool rethinks how moderation, c Third party licenses are available via the `/client/3rdpartylicenses.txt` endpoint when the server is running with built assets. -## Contributing to Talk - -See our [Contribution Guide](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md). - ## Documentation -### General - -See our [Talk Documentation & Guides](https://coralproject.github.io/talk/index.html). - -### Plugins - -See our guide to using and building [Talk Plugins](https://github.com/coralproject/talk/blob/master/PLUGINS.md). - -### Recipes - -Recipes are plugin templates provided by the Coral Core team. Developers can use these recipes to build their own plugins. You can find all the Talk recipes here: https://github.com/coralproject/talk-recipes/ - -## Usage - -### Installation - -To set up a development environment or build from source, see [INSTALL.md](https://github.com/coralproject/talk/blob/master/INSTALL.md). - -To launch a Talk server of your own from your browser without any need to muck about in a terminal or think about engineering concepts, stay tuned. We will launch [our installer](https://github.com/coralproject/talk-install) shortly! - -### Configuration - -The Talk application looks for the following configuration values either as environment variables: - -- `TALK_MONGO_URL` (*required*) - the database connection string for the MongoDB database. -- `TALK_REDIS_URL` (*required*) - the database connection string for the Redis database. -- `TALK_ROOT_URL` (*required*) - root url of the installed application externally -available in the format: `://` without the path. -- `TALK_JWT_SECRET` (*required*) - a long and cryptographical secure random string which will be used to -sign and verify tokens via a `HS256` algorithm. -- `TALK_JWT_EXPIRY` (_optional_) - the expiry duration (`exp`) for the tokens issued for logged in sessions (Default `1 day`) -- `TALK_JWT_ISSUER` (_optional_) - the issuer (`iss`) claim for login JWT tokens (Default `process.env.TALK_ROOT_URL`) -- `TALK_JWT_AUDIENCE` (_optional_) - the audience (`aud`) claim for login JWT tokens (Default `talk`) -- `TALK_SMTP_EMAIL` (*required for email*) - the address to send emails from using the - SMTP provider. -- `TALK_SMTP_USERNAME` (*required for email*) - username of the SMTP provider you are using. -- `TALK_SMTP_PASSWORD` (*required for email*) - password for the SMTP provider you are using. -- `TALK_SMTP_HOST` (*required for email*) - SMTP host url with format `smtp.domain.com`. -- `TALK_SMTP_PORT` (*required for email*) - SMTP port. -- `TALK_INSTALL_LOCK` (_optional for dynamic setup_) - When `TRUE`, disables the dynamic setup endpoint. (Default `FALSE`) -- `TALK_RECAPTCHA_SECRET` (*required for reCAPTCHA support*) - server secret used for enabling reCAPTCHA powered logins. If not provided it will instead default to providing only a time based lockout. -- `TALK_RECAPTCHA_PUBLIC` (*required for reCAPTCHA support*) - client secret used for enabling reCAPTCHA powered logins. If not provided it will instead default to providing only a time based lockout. -- `TALK_PLUGINS_JSON` (_optional_) - used to specify the plugin config via the environment -- `TALK_KEEP_ALIVE` (_optional_) - The keepalive timeout that should be used to send keep alive messages through the websocket to keep the socket alive. (Default `30s`) -- `TALK_DISABLE_AUTOFLAG_SUSPECT_WORDS` (_optional_) When `TRUE`, disables flagging of comments that match the suspect word filter. (Default `FALSE`) - -Refer to the wiki page on [Configuration Loading](https://github.com/coralproject/talk/wiki/Configuration-Loading) for -alternative methods of loading configuration during development. - -### Running Migrations - -We have a migration tool that can be run using `bin/cli migration run`. This will detect new migrations available and prompt you to backup your database before proceeding with the migration. Migrations are required with major version releases. - -### Using Trust - -Talk ships with core components we call "Trust". This allows Talk to automate certain actions based on previous user behavior. - -Our first feature is the notion of Karma. Talk will automatically pre-moderate comments of users who have a negative karma score. You can [see more how karma works here](/services/karma.js). - -## Supported Browsers - -### Web - -- Chrome: latest 2 versions -- Firefox: latest 2 versions, and most recent extended support version, if any -- Safari: latest 2 versions -- Internet Explorer: IE Edge, 11 - -### iOS Devices - -- iPad -- iPad Pro -- iPhone 7 Plus -- iPhone 7 -- iPhone 6 Plus -- iPhone 6 -- iPhone 5 - -### iOS Browsers - -- Chrome for iOS: latest version -- Firefox for iOS: latest version -- Safari for iOS: latest version - -### Android Devices - -- Galaxy S5 -- Nexus 5X -- Nexus 6P - -### Android Browsers - -- Chrome for Android: latest version -- Firefox for Android: latest version +See our [Talk Documentation & Guides](https://coralproject.github.io/talk/). ## License diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md deleted file mode 100644 index b95dbb816..000000000 --- a/TERMINOLOGY.md +++ /dev/null @@ -1,73 +0,0 @@ -# Product's Terminology - -This is a guide to have a common language to talk about "Talk". - -## Definitions - -* Site - a top level site, aka nytimes.com -* Section - the section of a site, aka, Politics. -* Subsection - the section of a site, aka, Politics. -* Asset - An article/video/etc identified by URL. - -* Embed - Things we put on a asset: comment box, ToS, Stream, etc… -* Stream - All the activity on a certain asset. Container for Comments, actions, user -* Thread - defined by a parent and everything below. All replies to a comment and their replies, etc… -* Comment - a kind of user-generated content submitted by a comment author - * A parent comment has replies to it - * A child comments is a reply to another comment - * A comment can be both a parent comment and a child of another comment - * A top-level comment is a comment that is not a reply to any other comment - * A nth-level comment refers to the number of replies away from the top-level comment - -* User - an item to represent a person using Talk. It could be a moderator, reader, etc. -* User Roles: - * Active: some who takes action (logged in or not) - * Passive: some who just reads, no actions performed - * Comment Author: The user who wrote the comment - * Staff Member: someone who works for an organization (tagged for leverage in trust) - * Moderator: someone with the ability to access the moderation queue and perform moderation actions - * Administrator: has the ability to change the setup of their coral space -* Public Profile: information about users shown in public -* Private Profile: information about users shown only to user about themselves -* Protected Profile: information about users that only moderators and admins can see - -* Queue - Group of items based on a query, aka - moderation queue -* Target - The item/s on which an action is performed - -## Actions - -Actions are performed by users on items. Actions themselves are items. This requires two relationships: action on item, and user performs action. - -### Flag -* A Flagger(user) performs a Flag -* A Flag is performed on a Comment or a username or profile content - - -## Moderation Actions and Status - -Comments contain a field `status`. As moderation actions are peformed, the status changes. - -* Initial status is empty. -* When a moderator Approves, the status is set to 'approved'. -* When a moderator Rejects, the status is set to 'reject'. - -### Pre and post moderation - -Comments can be set to be premoderated or postmoderated. - -Premoderation means that moderation has to occur _before_ a comment is shown on the site: - -* New comments are shown in the moderator queues immediately. -* The are not shown to users until (aka in streams) until they are approved by a moderator. - -Postmoderation means that comments appear on the site _before_ any moderation action is taken. - -* New comments appear in comment streams immediately. -* New comments do not appear in moderation queues unless they are flagged by other users. - -### Word lists - -* Banned words - words that the site never allows in a comment -* Suspect words - words whose usage needs to be approved by a moderator before being shown in the stream -* Approved words - words that are usually Banned or Suspect sitewide, but approved for use in a specific article stream - diff --git a/config.js b/config.js index 5d76c8d0f..83cb5089f 100644 --- a/config.js +++ b/config.js @@ -125,6 +125,12 @@ if (process.env.NODE_ENV === 'test' && !CONFIG.JWT_SECRET) { ); } +// If this is not employing a HMAC based signing method, then we need to turn +// the secret into a buffer. +if (!CONFIG.JWT_ALG.startsWith('HS')) { + CONFIG.JWT_SECRET = Buffer.from(CONFIG.JWT_SECRET); +} + //------------------------------------------------------------------------------ // External database url's //------------------------------------------------------------------------------ diff --git a/docs/.vscode/settings.json b/docs/.vscode/settings.json deleted file mode 100644 index 5af001d55..000000000 --- a/docs/.vscode/settings.json +++ /dev/null @@ -1,6 +0,0 @@ -// Place your settings in this file to overwrite default and user settings. -{ - "files.associations": { - "*.html": "liquid" - } -} diff --git a/docs/404.md b/docs/404.md deleted file mode 100644 index a7b58c002..000000000 --- a/docs/404.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Page Not Found" -search: exclude ---- - -Sorry, but the page you were trying to view does not exist. Try searching for it or looking at the URL to see if it looks correct. diff --git a/docs/Dockerfile b/docs/Dockerfile deleted file mode 100644 index b1fa52c47..000000000 --- a/docs/Dockerfile +++ /dev/null @@ -1,26 +0,0 @@ -FROM ruby:2.1 -MAINTAINER mrafayaleem@gmail.com - -RUN apt-get clean \ - && mv /var/lib/apt/lists /var/lib/apt/lists.broke \ - && mkdir -p /var/lib/apt/lists/partial - -RUN apt-get update - -RUN apt-get install -y \ - node \ - python-pygments \ - && apt-get clean \ - && rm -rf /var/lib/apt/lists/ - -WORKDIR /tmp -ADD Gemfile /tmp/ -ADD Gemfile.lock /tmp/ -RUN bundle install - -VOLUME /src -EXPOSE 4000 - -WORKDIR /src -ENTRYPOINT ["jekyll"] - diff --git a/docs/Gemfile b/docs/Gemfile old mode 100644 new mode 100755 index d2e1a4527..0dee02654 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -1,4 +1,11 @@ source "https://rubygems.org" -gem 'github-pages', group: :jekyll_plugins -gem 'wdm', '>= 0.1.0' if Gem.win_platform? +gem "github-pages", group: :jekyll_plugins + +group :jekyll_plugins do + gem "jekyll-paginate" + gem "jekyll-sitemap" + gem "jekyll-gist" + gem "jekyll-feed" + gem "jemoji" +end \ No newline at end of file diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 04ce5e261..adda86bbd 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -11,7 +11,7 @@ GEM coffee-script (2.4.1) coffee-script-source execjs - coffee-script-source (1.12.2) + coffee-script-source (1.11.1) colorator (1.1.0) ethon (0.10.1) ffi (>= 1.3.0) @@ -21,22 +21,22 @@ GEM ffi (1.9.18) forwardable-extended (2.6.0) gemoji (3.0.0) - github-pages (138) + github-pages (145) activesupport (= 4.2.8) - github-pages-health-check (= 1.3.3) - jekyll (= 3.4.3) + github-pages-health-check (= 1.3.4) + jekyll (= 3.4.5) jekyll-avatar (= 0.4.2) jekyll-coffeescript (= 1.0.1) jekyll-default-layout (= 0.1.4) jekyll-feed (= 0.9.2) jekyll-gist (= 1.4.0) - jekyll-github-metadata (= 2.3.1) + jekyll-github-metadata (= 2.5.1) jekyll-mentions (= 1.2.0) - jekyll-optional-front-matter (= 0.1.2) + jekyll-optional-front-matter (= 0.2.0) jekyll-paginate (= 1.1.0) jekyll-readme-index (= 0.1.0) jekyll-redirect-from (= 0.12.1) - jekyll-relative-links (= 0.4.0) + jekyll-relative-links (= 0.4.1) jekyll-sass-converter (= 1.5.0) jekyll-seo-tag (= 2.2.3) jekyll-sitemap (= 1.0.0) @@ -50,11 +50,11 @@ GEM jekyll-theme-midnight (= 0.0.4) jekyll-theme-minimal (= 0.0.4) jekyll-theme-modernist (= 0.0.4) - jekyll-theme-primer (= 0.1.8) + jekyll-theme-primer (= 0.3.1) jekyll-theme-slate (= 0.0.4) jekyll-theme-tactile (= 0.0.4) jekyll-theme-time-machine (= 0.0.4) - jekyll-titles-from-headings (= 0.1.5) + jekyll-titles-from-headings (= 0.2.0) jemoji (= 0.8.0) kramdown (= 1.13.2) liquid (= 3.0.6) @@ -63,7 +63,7 @@ GEM minima (= 2.1.1) rouge (= 1.11.1) terminal-table (~> 1.4) - github-pages-health-check (1.3.3) + github-pages-health-check (1.3.4) addressable (~> 2.3) net-dns (~> 0.8) octokit (~> 4.0) @@ -72,8 +72,8 @@ GEM html-pipeline (2.6.0) activesupport (>= 2) nokogiri (>= 1.4) - i18n (0.8.1) - jekyll (3.4.3) + i18n (0.8.6) + jekyll (3.4.5) addressable (~> 2.4) colorator (~> 1.0) jekyll-sass-converter (~> 1.0) @@ -94,21 +94,21 @@ GEM jekyll (~> 3.3) jekyll-gist (1.4.0) octokit (~> 4.2) - jekyll-github-metadata (2.3.1) + jekyll-github-metadata (2.5.1) jekyll (~> 3.1) octokit (~> 4.0, != 4.4.0) jekyll-mentions (1.2.0) activesupport (~> 4.0) html-pipeline (~> 2.3) jekyll (~> 3.0) - jekyll-optional-front-matter (0.1.2) + jekyll-optional-front-matter (0.2.0) jekyll (~> 3.0) jekyll-paginate (1.1.0) jekyll-readme-index (0.1.0) jekyll (~> 3.0) jekyll-redirect-from (0.12.1) jekyll (~> 3.3) - jekyll-relative-links (0.4.0) + jekyll-relative-links (0.4.1) jekyll (~> 3.3) jekyll-sass-converter (1.5.0) sass (~> 3.4) @@ -135,7 +135,7 @@ GEM jekyll (~> 3.3) jekyll-theme-modernist (0.0.4) jekyll (~> 3.3) - jekyll-theme-primer (0.1.8) + jekyll-theme-primer (0.3.1) jekyll (~> 3.3) jekyll-theme-slate (0.0.4) jekyll (~> 3.3) @@ -143,7 +143,7 @@ GEM jekyll (~> 3.3) jekyll-theme-time-machine (0.0.4) jekyll (~> 3.3) - jekyll-titles-from-headings (0.1.5) + jekyll-titles-from-headings (0.2.0) jekyll (~> 3.3) jekyll-watch (1.5.0) listen (~> 3.0, < 3.1) @@ -158,25 +158,29 @@ GEM rb-fsevent (>= 0.9.3) rb-inotify (>= 0.9.7) mercenary (0.3.6) - mini_portile2 (2.1.0) + mini_portile2 (2.2.0) minima (2.1.1) jekyll (~> 3.3) minitest (5.10.2) multipart-post (2.0.0) net-dns (0.8.0) - nokogiri (1.6.8.1) - mini_portile2 (~> 2.1.0) + nokogiri (1.8.0) + mini_portile2 (~> 2.2.0) octokit (4.7.0) sawyer (~> 0.8.0, >= 0.5.3) pathutil (0.14.0) forwardable-extended (~> 2.6) public_suffix (2.0.5) - rb-fsevent (0.9.8) - rb-inotify (0.9.8) - ffi (>= 0.5.0) + rb-fsevent (0.10.2) + rb-inotify (0.9.10) + ffi (>= 0.5.0, < 2) rouge (1.11.1) safe_yaml (1.0.4) - sass (3.4.24) + sass (3.5.1) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) sawyer (0.8.1) addressable (>= 2.3.5, < 2.6) faraday (~> 0.8, < 1.0) @@ -187,13 +191,18 @@ GEM ethon (>= 0.8.0) tzinfo (1.2.3) thread_safe (~> 0.1) - unicode-display_width (1.2.1) + unicode-display_width (1.3.0) PLATFORMS ruby DEPENDENCIES github-pages + jekyll-feed + jekyll-gist + jekyll-paginate + jekyll-sitemap + jemoji BUNDLED WITH - 1.15.0 + 1.15.2 diff --git a/docs/licenses/LICENSE b/docs/LICENSE.txt old mode 100644 new mode 100755 similarity index 96% rename from docs/licenses/LICENSE rename to docs/LICENSE.txt index e04b3d02e..b7cc9a0dc --- a/docs/licenses/LICENSE +++ b/docs/LICENSE.txt @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2016 Tom Johnson +Copyright (c) 2017 Michael Rose Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +SOFTWARE. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..b5637517d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Coral Talk Documentation + +To preview the documentation, run: + +```bash +docker run --rm --volume=$PWD:/srv/jekyll -p 127.0.0.1:4000:4000 -it jekyll/jekyll:pages jekyll serve +``` + +From the `docs` directory. Then visit: [http://127.0.0.1:4000/talk/](http://127.0.0.1:4000/talk/). \ No newline at end of file diff --git a/docs/Rakefile b/docs/Rakefile new file mode 100755 index 000000000..e50d89f84 --- /dev/null +++ b/docs/Rakefile @@ -0,0 +1,75 @@ +require "bundler/gem_tasks" +require "jekyll" +require "listen" + +def listen_ignore_paths(base, options) + [ + /_config\.ya?ml/, + /_site/, + /\.jekyll-metadata/ + ] +end + +def listen_handler(base, options) + site = Jekyll::Site.new(options) + Jekyll::Command.process_site(site) + proc do |modified, added, removed| + t = Time.now + c = modified + added + removed + n = c.length + relative_paths = c.map{ |p| Pathname.new(p).relative_path_from(base).to_s } + print Jekyll.logger.message("Regenerating:", "#{relative_paths.join(", ")} changed... ") + begin + Jekyll::Command.process_site(site) + puts "regenerated in #{Time.now - t} seconds." + rescue => e + puts "error:" + Jekyll.logger.warn "Error:", e.message + Jekyll.logger.warn "Error:", "Run jekyll build --trace for more information." + end + end +end + +task :preview do + base = Pathname.new('.').expand_path + options = { + "source" => base.join('test').to_s, + "destination" => base.join('test/_site').to_s, + "force_polling" => false, + "serving" => true, + "theme" => "minimal-mistakes-jekyll" + } + + options = Jekyll.configuration(options) + + ENV["LISTEN_GEM_DEBUGGING"] = "1" + listener = Listen.to( + base.join("_includes"), + base.join("_layouts"), + base.join("_sass"), + base.join("assets"), + options["source"], + :ignore => listen_ignore_paths(base, options), + :force_polling => options['force_polling'], + &(listen_handler(base, options)) + ) + + begin + listener.start + Jekyll.logger.info "Auto-regeneration:", "enabled for '#{options["source"]}'" + + unless options['serving'] + trap("INT") do + listener.stop + puts " Halting auto-regeneration." + exit 0 + end + + loop { sleep 1000 } + end + rescue ThreadError + # You pressed Ctrl-C, oh my! + end + + Jekyll::Commands::Serve.process(options) +end diff --git a/docs/_config.yml b/docs/_config.yml old mode 100644 new mode 100755 index 96ae10d52..f4f3b21a4 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,102 +1,252 @@ -repository: coralproject/talk +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your entire site, values +# which you are expected to set up once and rarely need to edit after that. +# For technical reasons, this file is *NOT* reloaded automatically when you use +# `jekyll serve`. If you change this file, please restart the server process. -output: web -# this property is useful for conditional filtering of content that is separate from the PDF. +# Site Settings +locale : "en" +title : "Coral Talk Documentation" +title_separator : "-" +name : "The Coral Project" +description : "Documentation and guides for Coral Talk." +url : https://coralproject.github.io # the base hostname & protocol for your site e.g. "https://mmistakes.github.io" +baseurl : /talk # the subpath of your site, e.g. "/blog" +repository : "coralproject/talk" # GitHub username/repo-name e.g. "mmistakes/minimal-mistakes" +teaser : # path of fallback teaser image, e.g. "/assets/images/500x300.png" +# breadcrumbs : false # true, false (default) +words_per_minute : 200 +comments: + provider : # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman", "custom" + disqus: + shortname : # https://help.disqus.com/customer/portal/articles/466208-what-s-a-shortname- + discourse: + server : # https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963 , e.g.: meta.discourse.org + facebook: + # https://developers.facebook.com/docs/plugins/comments + appid : + num_posts : # 5 (default) + colorscheme : # "light" (default), "dark" +staticman: + allowedFields : ['name', 'email', 'url', 'message'] + branch : "master" + commitMessage : "New comment." + filename : comment-{@timestamp} + format : "yml" + moderation : true + path : "docs/_data/comments/{options.slug}" # "/_data/comments/{options.slug}" (default) + requiredFields : ['name', 'email', 'message'] + transforms: + email : "md5" + generatedFields: + date: + type : "date" + options: + format : "iso8601" # "iso8601" (default), "timestamp-seconds", "timestamp-milliseconds" +atom_feed: + path : # blank (default) uses feed.xml -topnav_title: Coral Talk Documentation -# this appears on the top navigation bar next to the home button +# SEO Related +google_site_verification : +bing_site_verification : +alexa_site_verification : +yandex_site_verification : -site_title: Coral Talk Documentation -# this appears in the html browser tab for the site title (seen mostly by search engines, not users) +# Social Sharing +twitter: + username : +facebook: + username : + app_id : + publisher : +og_image : # Open Graph/Twitter default site image +# For specifying social profiles +# - https://developers.google.com/structured-data/customize/social-profiles +social: + type : # Person or Organization (defaults to Person) + name : # If the user or organization name differs from the site's name + links: # An array of links to social media profiles -company_name: The Coral Project -# this appears in the footer +# Analytics +analytics: + provider : false # false (default), "google", "google-universal", "custom" + google: + tracking_id : -github_editme_path: -# if you're using Github, provide the basepath to the branch you've created for reviews, following the sample here. if not, leave this value blank. -disqus_shortname: -# if you're using disqus for comments, add the shortname here. if not, leave this value blank. +# Site Author +author: + name : "Your Name" + avatar : # path of avatar image, e.g. "/assets/images/bio-photo.jpg" + bio : "I am an amazing person." + location : "Somewhere" + email : + uri : + bitbucket : + codepen : + dribbble : + flickr : + facebook : + foursquare : + github : + gitlab : + google_plus : + keybase : + instagram : + lastfm : + linkedin : + pinterest : + soundcloud : + stackoverflow : # "123456/username" (the last part of your profile url, e.g. http://stackoverflow.com/users/123456/username) + steam : + tumblr : + twitter : + vine : + weibo : + xing : + youtube : # "https://youtube.com/c/MichaelRoseDesign" -host: 127.0.0.1 -# the preview server used. Leave as is. - -port: 4000 -# the port where the preview is rendered. You can leave this as is unless you have other Jekyll builds using this same port that might cause conflicts. in that case, use another port such as 4006. +# Reading Files +include: + - .htaccess + - swagger.yml + - _pages exclude: - - .idea/ - - .gitignore -# these are the files and directories that jekyll will exclude from the build + - "*.sublime-project" + - "*.sublime-workspace" + - vendor + - .asset-cache + - .bundle + - .jekyll-assets-cache + - .sass-cache + - assets/js/plugins + - assets/js/_main.js + - assets/js/vendor + - Capfile + - CHANGELOG + - config + - Gemfile + - Gruntfile.js + - gulpfile.js + - LICENSE + - log + - node_modules + - package.json + - Rakefile + - README.md + - tmp +keep_files: + - .git + - .svn +encoding: "utf-8" +markdown_ext: "markdown,mkdown,mkdn,mkd,md" -feedback_subject_line: - -feedback_email: -# used as a contact email for the Feedback link in the top navigation bar - - feedback_disable: true -# if you uncomment the previous line, the Feedback link gets removed - -# feedback_text: "Need help?" -# if you uncomment the previous line, it changes the Feedback text - -# feedback_link: "http://helpy.io/" -# if you uncomment the previous line, it changes where the feedback link points to - -highlighter: rouge -# library used for syntax highlighting +# Conversion markdown: kramdown +highlighter: rouge +lsi: false +excerpt_separator: "\n\n" +incremental: false + + +# Markdown Processing kramdown: - input: GFM - auto_ids: true - hard_wrap: false - syntax_highlighter: rouge + input: GFM + hard_wrap: false + auto_ids: true + footnote_nr: 1 + entity_output: as_char + toc_levels: 1..6 + smart_quotes: lsquo,rsquo,ldquo,rdquo + enable_coderay: false -# filter used to process markdown. note that kramdown differs from github-flavored markdown in some subtle ways +# Sass/SCSS +sass: + sass_dir: _sass + style: compressed # http://sass-lang.com/documentation/file.SASS_REFERENCE.html#output_style + + +# Outputting +permalink: /:categories/:title/ +paginate: 5 # amount of posts to show +paginate_path: /page:num/ +timezone: # http://en.wikipedia.org/wiki/List_of_tz_database_time_zones + + +# Plugins (previously gems:) +plugins: + - jekyll-paginate + - jekyll-sitemap + - jekyll-gist + - jekyll-feed + - jemoji + +# mimic GitHub Pages with --safe +whitelist: + - jekyll-paginate + - jekyll-sitemap + - jekyll-gist + - jekyll-feed + - jemoji + + +# Archives +# Type +# - GitHub Pages compatible archive pages built with Liquid ~> type: liquid (default) +# - Jekyll Archives plugin archive pages ~> type: jekyll-archives +# Path (examples) +# - Archive page should exist at path when using Liquid method or you can +# expect broken links (especially with breadcrumbs enabled) +# - /tags/my-awesome-tag/index.html ~> path: /tags/ +# - path: /categories/ +# - path: / +# category_archive: +# type: liquid +# path: /categories/ +# tag_archive: +# type: liquid +# path: /tags/ +# https://github.com/jekyll/jekyll-archives +# jekyll-archives: +# enabled: +# - categories +# - tags +# layouts: +# category: archive-taxonomy +# tag: archive-taxonomy +# permalinks: +# category: /categories/:name/ +# tag: /tags/:name/ + + +# HTML Compression +# - http://jch.penibelst.de/ +compress_html: + clippings: all + ignore: + envs: development + +# Collections collections: - tooltips: - output: false -# collections are declared here. this renders the content in _tooltips and processes it, but doesn't output it as actual files in the output unless you change output to true + docs: + output: true + permalink: /:collection/:path/ +# Defaults defaults: - - - scope: + # _docs + - scope: path: "" - type: "pages" + type: docs values: - layout: "page" - comments: true - search: true - sidebar: talk_sidebar - - - scope: - path: "" - type: "tooltips" - values: - layout: "page" - comments: true - search: true - tooltip: true - - - - scope: - path: "" - type: "posts" - values: - layout: "post" - comments: true - search: true - sidebar: home_sidebar - -# these are defaults used for the frontmatter for these file types - -sidebars: -- talk_sidebar - -description: "Documentation and guides for Coral Talk." -# the description is used in the feed.xml file - -# needed for sitemap.xml file only -url: https://coralproject.github.io/talk/ + layout: single + read_time: false + author_profile: false + share: false + comments: false + sidebar: + nav: "docs" diff --git a/docs/_data/alerts.yml b/docs/_data/alerts.yml deleted file mode 100644 index 157e1622b..000000000 --- a/docs/_data/alerts.yml +++ /dev/null @@ -1,15 +0,0 @@ -tip: '