Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document command-line-interface of importers #507

Merged
merged 4 commits into from
Dec 18, 2022
Merged

Document command-line-interface of importers #507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
eef3313
Document command-line-interface of importers
ashmaroli Dec 16, 2022
afc7280
Use `relative_url` filter to render key links
ashmaroli Dec 16, 2022
b116c38
Define default front matter via conventional YAML
ashmaroli Dec 18, 2022
679d6ac
Use a plugin to set Netlify Deploy Preview URL
ashmaroli Dec 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/_config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,17 @@ collections:
output: true
importers:
output: true
permalink: /docs/:path/

defaults:
- scope:
type: docs
values:
layout: docs
- scope:
type: importers
values:
layout: importer

sass:
style: compressed
14 changes: 0 additions & 14 deletions docs/_importers/behance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,7 @@
---
layout: docs
title: Behance
importer: true
prev_section: usage
link_source: behance
next_section: blogger
permalink: /docs/behance/
---

To import your posts from your [Behance](http://behance.com), generate an API token for your user account and run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Behance.run({
"user" => "my_username",
"api_token" => "my_api_token"
})'
{% endhighlight %}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The plugin you wrote is super cool and the final output is amazing! I'm kind of sad that a reader of this Jekyll site source wouldn't actually get to see much of the content that they'd view in the output. It simultaneously shows the power of Jekyll ("you can inject all sorts of content at build time!") and the drawback of that power ("a lot of the key content on the site isn't in the source files"). I wonder if it would make sense for either (1) us to generate the content into the site source which we push up to the repo or (2) the plugin to inject a variable into the Liquid template so our page can at least have a reference like {{ auto_generated_usage_guide }}. Some food for thought. Right now it's very magical but I'm debating if maybe it separates the source and final output too much?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For hosted metadata, we could generate another data file for CLI information using a Rake task just like we have one for the list of importer-dependencies.

But that is less exciting (for me, atleast) than having content generated automatically at runtime, especially because contributors / maintainers have to ensure the data file is updated as needed.
For example, say we add a new option to an importer or we make edits to the option-description, then

  • the data file has to be explicitly updated to ensure the change gets documented.
  • Maintainers would have to explicitly check if the pull request has the data file updated to match the proposed change before merging the PR.

Regarding the Liquid object autogenerated..., that too is possible, but I am not yet clear on the suggested use-case.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good points. Let's leave it how you have it now.


Both `user` and `api_token` are required.
26 changes: 5 additions & 21 deletions docs/_importers/blogger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,13 @@
---
layout: docs
title: Blogger
importer: true
prev_section: behance
link_source: blogger
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Side note: could we lexically alphabetize the list of importers and set these in a plugin or in Liquid too? This seems a bit inefficient to list them all here. When adding a new importer, the contributor has to know the order of their new importer in the context of other importers which we could easily get a computer to figure that out.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically, this is not needed at all. At least with modern Jekyll because basically there's already the concept of next_doc and prev_doc for Jekyll::Document objects.
These were removed in the other pull request that made wholesale changes to the docs but left it untouched here to maintain the narrow scope of current PR.

next_section: csv
permalink: /docs/blogger/
---

To import your posts from your [Blogger](https://www.blogger.com/),
you first have to [export the blog][export-blogger-xml]
to a XML file (`blog-MM-DD-YYYY.xml`),
and run:
{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Blogger.run({
"source" => "/path/to/blog-MM-DD-YYYY.xml",
"no-blogger-info" => false, # not to leave blogger-URL info (id and old URL) in the front matter
"replace-internal-link" => false, # replace internal links using the post_url liquid tag.
})'
{% endhighlight %}
prereq_info: |-
To import your posts from Blogger, you have to first [export the blog][export-blogger-xml]
to an XML file (`blog-MM-DD-YYYY.xml`).

The only required field is `source`.
The other fields default to their above values.
[export-blogger-xml]: https://support.google.com/blogger/answer/97416 "Export or import your blog - Blogger Help"
---

"Labels" will be included in export as "Tags".

[export-blogger-xml]: https://support.google.com/blogger/answer/97416 "Export or import your blog - Blogger Help"
25 changes: 3 additions & 22 deletions docs/_importers/csv.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,10 @@
---
layout: docs
title: CSV
prev_section: blogger
link_source: csv
next_section: drupal6
permalink: /docs/csv/
---

To import your posts from a CSV file, run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::CSV.run({
"file" => "my_posts.csv"
})'
{% endhighlight %}

Your CSV file will be read in with the following columns:

1. title
Expand All @@ -24,14 +13,6 @@ Your CSV file will be read in with the following columns:
4. published_at
5. filter (e.g. markdown, textile)

If you wish to specify custom front matter for each of your posts, you
can use the `no-front-matter` option to prevent the default front matter
from being written to the imported files:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::CSV.run({
"file" => "my_posts.csv",
"no-front-matter" => true
})'
{% endhighlight %}
If you wish to specify custom front matter for each of your posts, you can use
the `--no-front-matter` option to prevent the default front matter from being
written to the imported files.
12 changes: 0 additions & 12 deletions docs/_importers/dotclear.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,6 @@
---
layout: docs
title: Dotclear
prev_section: csv
link_source: dotclear
next_section: drupal6
permalink: /docs/dotclear/
---

To import your posts from a dotclear file, run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Dotclear.run({
"datafile" => "2019-....-backup.txt",
"mediafolder" => "path/to/the/media (media.zip inflated)"
})'
{% endhighlight %}
35 changes: 1 addition & 34 deletions docs/_importers/drupal6.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,10 @@
---
layout: docs
title: Drupal 6
prev_section: csv
link_source: drupal6
next_section: drupal7
permalink: /docs/drupal6/
---

To import your posts from a [Drupal 6](http://drupal.org) installation, run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Drupal6.run({
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost",
"prefix" => "mytableprefix",
"types" => ["blog", "story", "article"]
})'
{% endhighlight %}

The only required fields are `dbname` and `user`. `password` defaults to `""`,
`host` defaults to `"localhost"`, and `prefix` defaults to `""`.

By default, this will pull in nodes of type `blog`, `story`, and `article`.
To specify custom types, you can use the `types` option when you run the
importer:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Drupal6.run({
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost",
"prefix" => "mytableprefix",
"types" => ["blog", "post"]
})'
{% endhighlight %}

That will import nodes of type `blog` and `post` only.
importer to select node types.
51 changes: 1 addition & 50 deletions docs/_importers/drupal7.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,10 @@
---
layout: docs
title: Drupal 7
prev_section: drupal6
link_source: drupal7
next_section: drupal8
permalink: /docs/drupal7/
---

To import your posts from a [Drupal 7](http://drupal.org) installation, run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Drupal7.run({
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost",
"prefix" => "mytableprefix",
"types" => ["blog", "story", "article"]
})'
{% endhighlight %}

The only required fields are `dbname` and `user`. `password` defaults to `""`,
`host` defaults to `"localhost"`, and `prefix` defaults to `""`.

By default, this will pull in nodes of type `blog`, `story`, and `article`.
To specify custom types, you can use the `types` option when you run the
importer:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Drupal7.run({
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost",
"prefix" => "mytableprefix",
"types" => ["blog", "post"]
})'
{% endhighlight %}

That will import nodes of type `blog` and `post` only.

The default Drupal 7 expects database to be MySQL. If you want to import posts
from Drupal 7 installation with PostgreSQL define `"engine"` as `"postgresql"`:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Drupal7.run({
"engine" => "postgresql",
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost",
"prefix" => "mytableprefix",
"types" => ["blog", "story", "article"]
})'
{% endhighlight %}
importer to select node types.
51 changes: 1 addition & 50 deletions docs/_importers/drupal8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,10 @@
---
layout: docs
title: Drupal 8
prev_section: drupal7
link_source: drupal8
next_section: easyblog
permalink: /docs/drupal8/
---

To import your posts from a [Drupal 8](http://drupal.org) installation, run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Drupal8.run({
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost",
"prefix" => "mytableprefix",
"types" => ["blog", "story", "article"]
})'
{% endhighlight %}

The only required fields are `dbname` and `user`. `password` defaults to `""`,
`host` defaults to `"localhost"`, and `prefix` defaults to `""`.

By default, this will pull in nodes of type `blog`, `story`, and `article`.
To specify custom types, you can use the `types` option when you run the
importer:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Drupal8.run({
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost",
"prefix" => "mytableprefix",
"types" => ["blog", "post"]
})'
{% endhighlight %}

That will import nodes of type `blog` and `post` only.

The default Drupal 8 expects database to be MySQL. If you want to import posts
from Drupal 8 installation with PostgreSQL define `"engine"` as `"postgresql"`:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Drupal8.run({
"engine" => "postgresql",
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost",
"prefix" => "mytableprefix",
"types" => ["blog", "story", "article"]
})'
{% endhighlight %}
importer to select node types.
19 changes: 0 additions & 19 deletions docs/_importers/easyblog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,6 @@
---
layout: docs
title: EasyBlog
prev_section: drupal8
link_source: easyblog
next_section: enki
permalink: /docs/easyblog/
---

To import your posts from a [EasyBlog](http://stackideas.com/easyblog) installation, run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Easyblog.run({
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost",
"prefix" => "mytableprefix"
})'
{% endhighlight %}

The only required fields are `dbname` and `user`. `password` defaults to `""`,
`host` defaults to `"localhost"`
`prefix` defaults to `"jos_"`. This will export all articles (in any state). Category and tags will be included in export.
18 changes: 0 additions & 18 deletions docs/_importers/enki.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,5 @@
---
layout: docs
title: Enki
prev_section: easyblog
link_source: enki
next_section: ghost
permalink: /docs/enki/
---

To import your posts from a [Enki](https://github.com/xaviershay/enki) installation, run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Enki.run({
"dbname" => "name",
"user" => "myuser",
"password" => "mypassword",
"host" => "myhost"
})'
{% endhighlight %}

The only required fields are `dbname` and `user`. `password` defaults to `""`
and `host` defaults to `"localhost"`.
19 changes: 4 additions & 15 deletions docs/_importers/ghost.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,10 @@
---
layout: docs
title: Ghost
prev_section: enki
link_source: ghost
next_section: google_reader
permalink: /docs/ghost/
---

To import your posts from your self-hosted Ghost instance, you first have to download your ghost.db from your server and run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::Ghost.run({
"dbfile" => "/path/to/your/ghost.db"
})'
{% endhighlight %}

There are no required fields. `dbfile` defaults to `"ghost.db"`.

If you have a Ghost backup file, consider using another tool called [jekyll_ghost_importer](https://github.com/eloyesp/jekyll_ghost_importer) to import your content. It is a separate gem and docs can be found at the link provided.
If you have a Ghost backup file, consider using another tool called
[jekyll_ghost_importer](https://github.com/eloyesp/jekyll_ghost_importer) to
import your content. It is a separate gem and docs can be found at the link
provided.
12 changes: 0 additions & 12 deletions docs/_importers/googlereader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,7 @@
---
layout: docs
title: Google Reader
prev_section: enki
link_source: google_reader
next_section: joomla
permalink: /docs/google_reader/
---

To import your posts from a [Google Reader](http://reader.google.com) XML dump file, run:

{% highlight bash %}
$ ruby -r rubygems -e 'require "jekyll-import";
JekyllImport::Importers::GoogleReader.run({
"source" => "my_file.xml"
})'
{% endhighlight %}

The `source` field is required.
Loading