Deploy docs from eccd783

Ashwin Maroli: Document command-line-interface of importers (#507) Merge pull request 507
jekyll · Dec 18, 2022 · b761d09 · b761d09
1 parent a5e6bc2
commit b761d09
Show file tree

Hide file tree

Showing 38 changed files with 1,717 additions and 491 deletions.
diff --git a/css/style.css b/css/style.css
diff --git a/css/style.css.map b/css/style.css.map
diff --git a/docs/behance/index.html b/docs/behance/index.html
@@ -243,7 +243,7 @@ <h1>
 
 
       <div class="unit four-fifths">
-        <article>
+        <article class="importer">
           <h1>Behance</h1>
 
 
@@ -277,15 +277,42 @@ <h5>Additional Dependencies</h5>
 
           </div>
 
-          <p>To import your posts from your <a href="http://behance.com">Behance</a>, generate an API token for your user account and run:</p>
+
+
+<h2>Invocation</h2>
+
+
+<p>
+  Sample snippet to invoke the importer:
+  <pre>jekyll import behance --user NAME --api_token TOKEN</pre>
+</p>
+
+<div class="table-container">
+  <table class="cli">
+    <tr><th>Option &lt;PARAM&gt;</th><th colspan="3">Description</th></tr>
+
+    <tr class="required-option">
+      <td><code>--user NAME</code></td>
+      <td colspan="2"><p>The username of the account</p>
+</td>
+
+    </tr>
+
+    <tr class="required-option">
+      <td><code>--api_token TOKEN</code></td>
+      <td colspan="2"><p>The API access token for the account</p>
+</td>
+
+    </tr>
+
+  </table>
+
+    <div class="cli-table-note">Highlighted row(s) in table above indicate required options.</div>
+
+</div>
+
 
-<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>ruby <span class="nt">-r</span> rubygems <span class="nt">-e</span> <span class="s1">'require "jekyll-import";
-    JekyllImport::Importers::Behance.run({
-      "user"      =&gt; "my_username",
-      "api_token" =&gt; "my_api_token"
-    })'</span></code></pre></figure>
 
-<p>Both <code class="language-plaintext highlighter-rouge">user</code> and <code class="language-plaintext highlighter-rouge">api_token</code> are required.</p>
 
 
             <div class="button">

diff --git a/docs/blogger/index.html b/docs/blogger/index.html
@@ -243,7 +243,7 @@ <h1>
 
 
       <div class="unit four-fifths">
-        <article>
+        <article class="importer">
           <h1>Blogger</h1>
 
 
@@ -277,20 +277,58 @@ <h5>Additional Dependencies</h5>
 
           </div>
 
-          <p>To import your posts from your <a href="https://www.blogger.com/">Blogger</a>,
-you first have to <a href="https://support.google.com/blogger/answer/97416" title="Export or import your blog - Blogger Help">export the blog</a>
-to a XML file (<code class="language-plaintext highlighter-rouge">blog-MM-DD-YYYY.xml</code>),
-and run:</p>
-
-<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>ruby <span class="nt">-r</span> rubygems <span class="nt">-e</span> <span class="s1">'require "jekyll-import";
-    JekyllImport::Importers::Blogger.run({
-      "source"                =&gt; "/path/to/blog-MM-DD-YYYY.xml",
-      "no-blogger-info"       =&gt; false, # not to leave blogger-URL info (id and old URL) in the front matter
-      "replace-internal-link" =&gt; false, # replace internal links using the post_url liquid tag.
-    })'</span></code></pre></figure>
-
-<p>The only required field is <code class="language-plaintext highlighter-rouge">source</code>.
-The other fields default to their above values.</p>
+
+
+<h2>Invocation</h2>
+<p>
+  <p>To import your posts from Blogger, you have to first <a href="https://support.google.com/blogger/answer/97416" title="Export or import your blog - Blogger Help">export the blog</a>
+to an XML file (<code class="language-plaintext highlighter-rouge">blog-MM-DD-YYYY.xml</code>).</p>
+
+
+</p>
+
+<p>
+  Sample snippet to invoke the importer:
+  <pre>jekyll import blogger --source NAME --no-blogger-info --replace-internal-link --comments</pre>
+</p>
+
+<div class="table-container">
+  <table class="cli">
+    <tr><th>Option &lt;PARAM&gt;</th><th colspan="3">Description</th></tr>
+
+    <tr class="required-option">
+      <td><code>--source NAME</code></td>
+      <td colspan="2"><p>The XML file (blog-MM-DD-YYYY.xml) path to import</p>
+</td>
+
+    </tr>
+
+    <tr>
+      <td><code>--no-blogger-info</code></td>
+      <td><p>not to leave blogger-URL info (id and old URL) in the front matter.</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>false</code></small></td>
+    </tr>
+
+    <tr>
+      <td><code>--replace-internal-link</code></td>
+      <td><p>replace internal links using the post_url liquid tag.</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>false</code></small></td>
+    </tr>
+
+    <tr>
+      <td><code>--comments</code></td>
+      <td><p>import comments to _comments collection.</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>false</code></small></td>
+    </tr>
+
+  </table>
+
+    <div class="cli-table-note">Highlighted row(s) in table above indicate required options.</div>
+
+</div>
 
 <p>“Labels” will be included in export as “Tags”.</p>
 

diff --git a/docs/contributing/index.html b/docs/contributing/index.html
@@ -243,7 +243,7 @@ <h1>
 
 
       <div class="unit four-fifths">
-        <article>
+        <article class="docs">
           <h1>Contributing</h1>
 
 

diff --git a/docs/csv/index.html b/docs/csv/index.html
@@ -243,17 +243,42 @@ <h1>
 
 
       <div class="unit four-fifths">
-        <article>
+        <article class="importer">
           <h1>CSV</h1>
 
 
 
-          <p>To import your posts from a CSV file, run:</p>
+
+
+<h2>Invocation</h2>
+
 
-<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>ruby <span class="nt">-r</span> rubygems <span class="nt">-e</span> <span class="s1">'require "jekyll-import";
-    JekyllImport::Importers::CSV.run({
-      "file" =&gt; "my_posts.csv"
-    })'</span></code></pre></figure>
+<p>
+  Sample snippet to invoke the importer:
+  <pre>jekyll import csv --file NAME --no-front-matter</pre>
+</p>
+
+<div class="table-container">
+  <table class="cli">
+    <tr><th>Option &lt;PARAM&gt;</th><th colspan="3">Description</th></tr>
+
+    <tr>
+      <td><code>--file NAME</code></td>
+      <td><p>The CSV file to import.</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>'posts.csv'</code></small></td>
+    </tr>
+
+    <tr>
+      <td><code>--no-front-matter</code></td>
+      <td><p>Do not add the default front matter to the post body.</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>false</code></small></td>
+    </tr>
+
+  </table>
+
+</div>
 
 <p>Your CSV file will be read in with the following columns:</p>
 
@@ -265,15 +290,9 @@ <h1>CSV</h1>
   <li>filter (e.g. markdown, textile)</li>
 </ol>
 
-<p>If you wish to specify custom front matter for each of your posts, you
-can use the <code class="language-plaintext highlighter-rouge">no-front-matter</code> option to prevent the default front matter
-from being written to the imported files:</p>
-
-<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>ruby <span class="nt">-r</span> rubygems <span class="nt">-e</span> <span class="s1">'require "jekyll-import";
-    JekyllImport::Importers::CSV.run({
-      "file" =&gt; "my_posts.csv",
-      "no-front-matter" =&gt; true
-    })'</span></code></pre></figure>
+<p>If you wish to specify custom front matter for each of your posts, you can use
+the <code class="language-plaintext highlighter-rouge">--no-front-matter</code> option to prevent the default front matter from being
+written to the imported files.</p>
 
 
 

diff --git a/docs/dotclear/index.html b/docs/dotclear/index.html
@@ -243,7 +243,7 @@ <h1>
 
 
       <div class="unit four-fifths">
-        <article>
+        <article class="importer">
           <h1>Dotclear</h1>
 
 
@@ -284,13 +284,41 @@ <h5>Additional Dependencies</h5>
 
           </div>
 
-          <p>To import your posts from a dotclear file, run:</p>
+
+
+<h2>Invocation</h2>
+
+
+<p>
+  Sample snippet to invoke the importer:
+  <pre>jekyll import dotclear --datafile PATH --mediafolder PATH</pre>
+</p>
+
+<div class="table-container">
+  <table class="cli">
+    <tr><th>Option &lt;PARAM&gt;</th><th colspan="3">Description</th></tr>
+
+    <tr class="required-option">
+      <td><code>--datafile PATH</code></td>
+      <td colspan="2"><p>dotClear export file</p>
+</td>
+
+    </tr>
+
+    <tr class="required-option">
+      <td><code>--mediafolder PATH</code></td>
+      <td colspan="2"><p>dotClear media export folder (media.zip inflated)</p>
+</td>
+
+    </tr>
+
+  </table>
+
+    <div class="cli-table-note">Highlighted row(s) in table above indicate required options.</div>
+
+</div>
+
 
-<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>ruby <span class="nt">-r</span> rubygems <span class="nt">-e</span> <span class="s1">'require "jekyll-import";
-    JekyllImport::Importers::Dotclear.run({
-      "datafile" =&gt; "2019-....-backup.txt",
-      "mediafolder" =&gt; "path/to/the/media (media.zip inflated)"
-    })'</span></code></pre></figure>
 
 
 

diff --git a/docs/drupal6/index.html b/docs/drupal6/index.html
@@ -243,7 +243,7 @@ <h1>
 
 
       <div class="unit four-fifths">
-        <article>
+        <article class="importer">
           <h1>Drupal 6</h1>
 
 
@@ -291,36 +291,86 @@ <h5>Additional Dependencies</h5>
 
           </div>
 
-          <p>To import your posts from a <a href="http://drupal.org">Drupal 6</a> installation, run:</p>
+
+
+<h2>Invocation</h2>
+
 
-<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>ruby <span class="nt">-r</span> rubygems <span class="nt">-e</span> <span class="s1">'require "jekyll-import";
-    JekyllImport::Importers::Drupal6.run({
-      "dbname"   =&gt; "name",
-      "user"     =&gt; "myuser",
-      "password" =&gt; "mypassword",
-      "host"     =&gt; "myhost",
-      "prefix"   =&gt; "mytableprefix",
-      "types"    =&gt; ["blog", "story", "article"]
-    })'</span></code></pre></figure>
+<p>
+  Sample snippet to invoke the importer:
+  <pre>jekyll import drupal6 --dbname DB --user USER --engine [mysql|postgresql] --password PW --host HOST --port PORT --prefix PREFIX --types TYPE1[,TYPE2[,TYPE3...]]</pre>
+</p>
 
-<p>The only required fields are <code class="language-plaintext highlighter-rouge">dbname</code> and <code class="language-plaintext highlighter-rouge">user</code>. <code class="language-plaintext highlighter-rouge">password</code> defaults to <code class="language-plaintext highlighter-rouge">""</code>,
-<code class="language-plaintext highlighter-rouge">host</code> defaults to <code class="language-plaintext highlighter-rouge">"localhost"</code>, and <code class="language-plaintext highlighter-rouge">prefix</code> defaults to <code class="language-plaintext highlighter-rouge">""</code>.</p>
+<div class="table-container">
+  <table class="cli">
+    <tr><th>Option &lt;PARAM&gt;</th><th colspan="3">Description</th></tr>
+
+    <tr class="required-option">
+      <td><code>--dbname DB</code></td>
+      <td colspan="2"><p>Database name</p>
+</td>
+
+    </tr>
+
+    <tr class="required-option">
+      <td><code>--user USER</code></td>
+      <td colspan="2"><p>Database user name</p>
+</td>
+
+    </tr>
+
+    <tr>
+      <td><code>--engine [mysql|postgresql]</code></td>
+      <td><p>Database engine</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>"mysql"</code></small></td>
+    </tr>
+
+    <tr>
+      <td><code>--password PW</code></td>
+      <td><p>Database user’s password</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>""</code></small></td>
+    </tr>
+
+    <tr>
+      <td><code>--host HOST</code></td>
+      <td><p>Database host name</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>"localhost"</code></small></td>
+    </tr>
+
+    <tr>
+      <td><code>--port PORT</code></td>
+      <td><p>Database port name</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>"3306"</code></small></td>
+    </tr>
+
+    <tr>
+      <td><code>--prefix PREFIX</code></td>
+      <td><p>Table prefix name</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>""</code></small></td>
+    </tr>
+
+    <tr>
+      <td><code>--types TYPE1[,TYPE2[,TYPE3...]]</code></td>
+      <td><p>The Drupal content types to be imported</p>
+</td>
+      <td><small>Default:&nbsp;&nbsp;<code>blog,story,article</code></small></td>
+    </tr>
+
+  </table>
+
+    <div class="cli-table-note">Highlighted row(s) in table above indicate required options.</div>
+
+</div>
 
 <p>By default, this will pull in nodes of type <code class="language-plaintext highlighter-rouge">blog</code>, <code class="language-plaintext highlighter-rouge">story</code>, and <code class="language-plaintext highlighter-rouge">article</code>.
 To specify custom types, you can use the <code class="language-plaintext highlighter-rouge">types</code> option when you run the
-importer:</p>
-
-<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>ruby <span class="nt">-r</span> rubygems <span class="nt">-e</span> <span class="s1">'require "jekyll-import";
-    JekyllImport::Importers::Drupal6.run({
-      "dbname"   =&gt; "name",
-      "user"     =&gt; "myuser",
-      "password" =&gt; "mypassword",
-      "host"     =&gt; "myhost",
-      "prefix"   =&gt; "mytableprefix",
-      "types"    =&gt; ["blog", "post"]
-    })'</span></code></pre></figure>
-
-<p>That will import nodes of type <code class="language-plaintext highlighter-rouge">blog</code> and <code class="language-plaintext highlighter-rouge">post</code> only.</p>
+importer to select node types.</p>
+
 
 
             <div class="button">