jekyll / jekyll-admin

A Jekyll plugin that provides users with a traditional CMS-style graphical interface to author content and administer Jekyll sites.

A Jekyll plugin that provides users with a traditional CMS-style graphical interface to author content and administer Jekyll sites. The project is divided into two parts. A Ruby-based HTTP API that handles Jekyll and filesystem operations, and a JavaScript-based front end, built on that API.

Installation

Refer to the installing plugins section of Jekyll's documentation and install the jekyll-admin plugin as you would any other plugin. Here's the short version:

1. Add the following to your site's Gemfile:

   gem 'jekyll-admin', group: :jekyll_plugins

2. Run bundle install

Usage

1. Start Jekyll as you would normally (bundle exec jekyll serve)
2. Navigate to http://localhost:4000/admin to access the administrative interface

Options

Jekyll Admin related options can be specified in _config.yml under a key called jekyll_admin.

jekyll_admin:
  hidden_links:
    - posts
    - pages
    - staticfiles
    - datafiles
    - configuration
  homepage: "pages"

Customizing collection label in Sidebar

The plugin allows you to customize the name of a collection that is displayed in the sidebar by defining it in the collection's metadata in the config file. For example, if your source's posts are actually news-items on the deployed site, then it can be distracting to see the label Posts in the admin's sidebar. This situation can be resolved with the following configuration:

collections:
  posts:
    output: true
    sidebar_label: News

Contributing

Interested in contributing to Jekyll Admin? We’d love your help. Jekyll Admin is an open source project, built one contribution at a time by users like you. See the contributing instructions, and the development docs for more information.

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

License

The gem is available as open source under the terms of the MIT License.

jekyll-admin's Issues

Paginate API responses

Eventually, it'd be nice to paginate the API responses for indexes on large sites.

Ability to edit site config

Allows users to create/edit/delete arbitrary YAML in the configuration file through an online editor:

Cannot GET /admin/pages/:id after refresh

In development mode, when visiting a page through the links works fine but refreshing the page results in 404 server error.

Whereabouts are the discussions/specifications for this project

Hi there,

I was just looking into doing something like this for a personal project when I found this.
I appreciate it's early days, but are there any specifications/documentation on what this project is ultimately aiming to do?

Thanks

Static file support

• Implement backend API
• Ability to edit list and upload static files

Updating document path fails

I think this is because server doesn’t expect folder prefix. For example, if the path is 2016-01-02-test2.md, it creates a file with the requested path but keeps the old one. If it has a folder prefix like this _posts/2016-01-02-test2.md, it completely fails. This line in the test fails to catch the bug.

/cc @benbalter

Check for invalid YAML

If users try to update a YAML file with invalid content, it gives parsing error and nothing is shown to users. Instead, an error message should be shown.

Frontend can't assume assume port

Right now, the front end assumes the server is running on localhost:3004.

While the default server port will be 4000, users can set that via a flag, so we shouldn't assume that either.

Ideally, the server would get the port from the URL it's being requested from, or from the server directly.

jekyll-admin gem can not be installed

Hi,
I'm trying to add jekyll-admin to a jekyll blog.
I added the gem in Gemfile and in _config.
When I give bundle install the following error is display.
What can I do in order to install jekyll-admin?

Fetching gem metadata from https://rubygems.org/                                                                                                                                 
Fetching version metadata from https://rubygems.org/                                                                                                                             
Fetching dependency metadata from https://rubygems.org/                                                                                                                          
Could not find gem 'jekyll-admin' in any of the gem sources listed in your                                                                                                       
Gemfile or available on this machine.    

Package as an Electron App

For an initial release, I'd imagine you'd still need to run jekyll serve to get the server running, but once you did, you could open Jekyll Admin, as a native desktop app, which would contain the packaged React client, and would make calls to the Jekyll server.

Eventually, it'd be cool if we could package Jekyll within Electron and run the server ourselves, perhaps on a non-standard port, including previews, but to start, it'd be nice to at least distribute the front end as a native app, for those that prefer a more native experience.

jekyll/admin or jekyll-admin?

Technically, technically, in Ruby land, jekyll/admin would be Jekyll::Admin and jekyll_admin would be JekyllAdmin.

In Jekyll land, we have a convention of calling everything jekyll-X (e.g.., jekyll-feed).

@parkr any strong feelings if this should be jekyll/admin or jekyll-admin?

Ability to create/update JSON data files

e.g., _data/foo.json versus _data/foo.yml. Based on the extension, we'll want to call to_json, rather than to_yaml.

Site publishing

• Implement backend
• Ability to commit and push to origin's default branch

Saving a page saves its computed/default front matter

Steps to reproduce:

1. Navigate to http://localhost:4000/admin/pages/page.md
2. Change the body content
3. Hit save

Expected:

Only the content is updated

Actual:

All fields written to disk including dir and front matter defaults.

Reloading after deleting file

I have been trying to implement the DELETE /pages/:pageid route and whenever I deleted a page, I was getting ERROR Errno::ENOENT: No such file or directory @ rb_sysopen - <page>.md when I tried to open the index route. This was due to the @site instance not being updated with the latest list of pages. Any idea how can I get around this? @parkr

Pages support

• Allows users to create/edit/delete Markdown-based pages through an online editor
• Allows users to create/edit/delete arbitrary YAML front matter in each page

Collection support

• Listing documents
• Allows users to create/edit/delete Markdown-based collections (including posts) through an online editor
• Allows users to create/edit/delete arbitrary YAML front matter in each document

Frontend should assume it's served from `/admin` not the server root

Right now, loading index.html assumes that paths to assets (e.g., bundle.js, style.css) are all served from the server root. Instead, the server should assume it's served from the /admin directory (e.g., /admin/bundle.js).

Allow CORS for dev server

Frontend dev server runs on port 3000 and sends requests to the API running on port 4000. This is only for development. For production, both runs on the same port anyway. This check differentiates the API url accordingly;

if (process.env.NODE_ENV === 'production') {
  API = '/_api';
} else {
  API = 'http://localhost:4000/_api';
}

However, difference between ports cause CORS now. What can we do about this?

Don't save empty metadata fields

Steps to reproduce:

1. Navigate to http://localhost:4000/admin/pages/page.md
2. Edit a metadata field
3. Hit save

Expected:

No new fields added

Actual:

"New field 1", "New field 2", "New field 3", etc. added to the front matter, even if they have no content.

Data file support

• Implement backend API
• Ability to edit _data files

Localization

• Ability to change the language of the front-end

Server throws `undefined method 'to_api'` if PUT request payloads have an empty `front_matter`

Search component disappears after a search with no results.

All resources should include their API URL

Similar to e.g., https://developer.github.com/v3/issues/#list-issues, the response for which, each issue object has a link to the resource, following true RESTful design patterns, we should inject API URLs in responses.

Server returning `null` after creating a data file with an extension

Standardize API

• Finalize API spec
• Fully document
• Consider versioning the API endpoints
• Tell the world

dependency error after installing the gem

Hey guys,

Thanks for the project! I tried to install the gem as shown below:

    group :jekyll_plugins do
      gem "jekyll-admin", github: "jekyll/jekyll-admin"
    end

Installing it directly (without github: "jekyll/jekyll-admin") caused error as shown below:

    ➜  new-site git:(master) bundle install
    Fetching gem metadata from https://rubygems.org/
    Fetching version metadata from https://rubygems.org/
    Fetching dependency metadata from https://rubygems.org/
    Could not find gem 'jekyll-admin' in any of the gem sources listed in your Gemfile or available on this machine.

    ➜  new-site git:(master) ✗ gem install jekyll-admin
    ERROR:  Could not find a valid gem 'jekyll-admin' (>= 0) in any repository
    ERROR:  Possible alternatives: jekyll-api, jekyll-cdn, jekyll-roman, jekyll-amazon, jekyll-auth

I've added gem name in _config.yml under gems and whitelist sections. After installation, when I hit commands below, I got errors shown below respectively:

    ➜  new-site git:(master) ✗ bundle exec jekyll serve --config _config.yml,_config.dev.yml 
    Configuration file: _config.yml
    Configuration file: _config.dev.yml
      Dependency Error: Yikes! It looks like you don't have jekyll-admin or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- jekyll-admin' If you run into trouble, you can find helpful resources at http://jekyllrb.com/help/! 
    jekyll 3.1.6 | Error:  jekyll-admin

    ➜  new-site git:(master) ✗ jekyll serve --config _config.yml,_config.dev.yml 
    WARN: Unresolved specs during Gem::Specification.reset:
          jekyll-watch (~> 1.1)
    WARN: Clearing out unresolved specs.
    Please report a bug if this causes problems.
    Configuration file: _config.yml
    Configuration file: _config.dev.yml
      Dependency Error: Yikes! It looks like you don't have jekyll-paginate or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- jekyll-paginate' If you run into trouble, you can find helpful resources at http://jekyllrb.com/help/! 
    jekyll 3.1.6 | Error:  jekyll-paginate

What goes wrong?

Package as an Atom plugin

Payload for API Requests

Looking at #79, #80, and #81, I think there's some ambiguity in terms of how to describe a document when making requests to and getting responses from the API. At least part of this is my fault, with the late addition of raw_content and front_matter fields via #61 and #53.

Whatever we do, I think it makes sense for the response and the request to be consistent.

Here's what I'd like to propose as the document (page, post, etc.) payload, and if it sounds good, I'll document it more formally:

• Top level keys are keys with special meaning. This includes:
  • Computed, read-only keys like url
  • Computed, read/write keys like path
  • Front matter defaults
• The top-level namespace will have content and raw_content keys with the HTML and markdown respectively
• The top-level namespace will have a front_matter key which includes the raw front matter as seen on disk.

A standard page may then look like this:

{  
   "some_front_matter":"default",
   "foo":"bar",
   "content":"<h1 id=\"test-page\">Test Page</h1>\n",
   "dir":"/",
   "name":"page.md",
   "path":"page.md",
   "url":"/page.html",
   "raw_content":"# Test Page\n",
   "front_matter":{  
      "foo":"bar"
   }
}

When making a request, clients can set the following top-level fields:

• raw_content - the raw, unrendered content to be written to disk (currently body)
• front_matter - the entire YAML front matter object to be written to disk (currently meta)
• path - the new file path relative to the site source, if the file is to be renamed

Does that make sense? Anything I'm missing? If so, will change the API to use raw_content and front_matter rather than body and meta and will update the docs accordingly.

Development Installation Not Working on Ubuntu 15.10 & 16.04

I was unable to run the scripts described on the development docs page. Here's an image of the errors that I got:

I also needed to add sudo in front of npm install -g json-server in script/bootstrap because the symlink that json-server was trying to create had a permissions issue. This might not happen on a mac? I'm not sure.

Gist of my npm-debug.log output.

Markdown edit box is writing rendered HTML, not raw markdown

E.g.:

Steps to reproduce:

1. Navigate to http://localhost:4000/admin/pages/page.md
2. Modify the markdown
3. Hit save

Expected:

Update markdown is saved and displayed

Actual:

• <h1 id="test-page">Test Page</h1> is saved to disk and displayed.
• raw_content metadata filed is saved with the content

@mertkahyaoglu this may be a miscommunication / need to change on the server side. I'm guessing you're sending raw_content as a metadata field, in addition to body?

Roadmap

A simple high-level roadmap would be be nice to share your vision on the project, at least to know what to expect and to be able to compare it with existing services like CloudCannon or similar open-source projects like https://github.com/gabriel-john/utterson that also aim at a functional UI for managing Jekyll-powered websites.

I guess the people at Github know exactly what they are doing and where they are going, maybe you will soon need help with prototyping UI or user testing before developing any new feature, we don't know. And if we don't know, we can not help.

When `GET /static_files/:path` is called on a directory, it should return that directory's static files

Note: that this should be the directory's static files, as seen by Jekyll, not all files in the directory.

Publish API documentation

Ability to read/write CSV data files

Similar to #106, this would allow the API to read, write and delete CSV data files in the _data folder, which Jekyll supports.

Travis for front-end

Can we enable travis for the front-end? I have never used it for subdirectories. I guess I should add something like this to .travis.yml;

script: cd lib/jekyll/admin/public && npm run test:cover:travis

Updating path gives internal server error

This is my payload;

{page_id: "page.md", meta: {foo: "baz", path: "page2.md"}, body: "# Test Page 1↵"}

I get 500 error when the path is not the same as the current one.

I believe this section should update the path, right? I'm using nameas an identifier for pages since no id field is present. Am I doing the opposite?

/cc @benbalter

Frontend should properly namespace API calls

Right now the front end server assumes all API calls live in a top-level namespace, (e.g., `/collections).

The site may have an existing /posts/ and /pages path that we don't want to clobber. To be safe, we should namespace the API endpoints.

I'm suggesting /_api/ (e.g., /_api/posts), since the _ convention is an existing Jekyll convention, and users are unlikely to have a generated _api path.

Document indexes shouldn't include document content

Otherwise, on a large site, with a lot of posts, the /posts/ endpoint would be extremely large.

Document object should include unrendered markdown content

I can fetch the all post documents. This is the result; (I added the title attribute to the front matter)

As you see, the response includes the document body (in html format but we have a markdown editor in the front-end).
Did we eliminate the GET /collections/:collection_name/documents/:id? Because I'm not able to fetch the post with id /2016/01/01/test. Although it is pointless since we have everything we need, I think.

Documents and Pages metadata contain frontmatter defaults

See #28 (comment).

I'd like to propose that we remove front matter defaults, even if explicitly present in the front matter. It's a compromise that isn't too difficult to implement technically, is better than the alternative, and has the added affect of removing duplicative front matter data.

Improve README and getting started experience for developers

It would be awesome if other developers who want to get involved could run jekyll-admin in a debug/development mode to help repro issues, offer PR feedback, or implement fixes.

The README is just a little too terse right now to make this straightforward.

missing are

• how to generate the UI (minified or unminified for debugging)
• basic configuration/assumptions: (how jekyll-admin knows what site to serve)
• how to install and run the plugin on a local jekyll site (in debug and non-debug mode)

Updating config adds `posts` to the `collections` section

Here are the steps to reproduce the issue.

1._config.yml includes the following content;

title: Your awesome title
collections:
  test:
    foo: bar
    output: true

2.Update the config (collection section must be present)

3._config.yml file now includes the following content;

title: Your awesome title
collections:
  posts:
    output: true
  test:
    foo: bar
    output: true

4.Delete the following lines;

posts:
  output: true

5.It deletes those lines from the file but the response to the front-end still has them.

Create new page : placeholder and valid user input

Some UX feedback after testing the creation of a new page:

• The placeholder when creating a new page is Filename, where as for a new post it is a valid example. I would suggest also a valid example here.
• There does not seem to be a validation on what is entered by the user when creating a page (or a post). So I can type "A new file" with spaces and no extension. But if I try to preview that kind of page, it will download the file instead of displaying it.

Redux State

@jldec I'm planning to structure my redux state as follows. What do you think ?

state : {

  configuration: {
    config: "title: Your awesome title\nemail: [email protected]..", // GET /configuration
    isFetching: false, // only render when fetched
    editorChanged: false, // for enabling save button on change,
    error: '', // e.g "Configuration updated.", "Error"
    updated: false // for Save/Saved button
  },

  pages: {
    pages: [ // GET /pages
      { page_id, body, meta },
      { page_id2, body2, meta2 }
    ],
    currentPage: { page_id, body, meta }, // GET /pages/:page_id
    isFetching: false,
    message: null,
  },

  collections: {
    collections: ['posts', 'movies'], // GET /collections
    currentCollection: { // GET /collections/:collection_name
      collection_name: 'posts',
      meta: {
        path: '/posts'
      }
    },
    currentDocuments: [ //GET /collections/:collection_name/documents
      {document_id, collection_name, meta},
      {document_id, collection_name, meta}
    ],
    currentDocument: { //GET /collections/:collection_name/documents/:document_id
      document_id,
      collection_name,
      body,
      meta
    },
    message: null
  },

  metadata: {
    layout: "post",
    categories: "gsoc",
    students: [
      {
        name: "Mert Kahyaoğlu",
        email: "[email protected]",
        username: "mertkahyaoglu"
      },
      {
        name: "Ankur Singh",
        email: "[email protected]",
        username: "rush-skills"
      }
    ],
    mentors: ["Ben Balter", "Jurgen Leschner", "Parker Moore"]
  },

  search: {
    input: ''
  },

  static_files: {
    files: [{path}, {path2}], // GET /static_files
    message: null
  },

  data: {
    files: [{path}, {path2}], // GET /data
    message: null
  },

  git: {
    status, // GET /git/status
    remote,
    branch,
    message: null
  }

}

Convert document IDs from `/YYYY/MM/DD/ID` to `YYYY-MM-DD-ID.md`

Per #35 (comment).

Should front-end remove `dist` folder on prestart?

After #86, front-end will be built on each start. This happens because it removes dist folder before starting (here). After that it starts test-server and building process starts.

Since npm start commands, here, runs in parallel, development server most likely will start before test-serverand front-end won't be able to show the contents until test-server is ready. What can we do about this?

Options;

• Do not run start commands in parallel.
• Do not remove dist folder before starting.

Plugin support

• Implement backend
• Ability to enable/disable plugins

Show post date in post index list

It'd be nice to show the date of posts for the post list (and to sort reverse chronologically by date, which we can do on the API level, if you want).

Other collections could theoretically have dates, but there's no programatic way to tell, so I think it's fine just to do this for posts for now.