Nellie McKesson
11 years ago
parent
cb29b59f15
commit
0da3dde7fa
@ -1,56 +1,109 @@
|
||||
<section data-type="chapter">
|
||||
<h1>Atlas Quick Start Guide</h1>
|
||||
<h1>Quick Start Guide</h1>
|
||||
|
||||
<p>How to start writing.</p>
|
||||
<p>Atlas is currently in its Alpha release; this means that, while we feel the system is ready to be used, it's still actively under development and needs some rigorous testing. That's where you come in! Here are the most important things you need to know to get started.</p>
|
||||
|
||||
<p>The visual editor vs. the code editor</p>
|
||||
<section data-type="sect1">
|
||||
<h1>Atlas (Alpha Release) Is Built on GitHub</h1>
|
||||
|
||||
<p>The alpha version of Atlas is built on <a data-original-title="" href="http://github.com" title="">GitHub</a>, one of the leading websites for collaborative file management using the <a data-original-title="" href="http://git-scm.com/" title="">git</a> version-control system. What this means for you is:</p>
|
||||
|
||||
<ul>
|
||||
<li><strong>You need a GitHub account</strong> in order to use Atlas (but if you've logged into Atlas by now, then you know this already).</li>
|
||||
<li>You can see <strong>all your personal GitHub repos</strong> in Atlas, as well as all the repos you have permission to access within any organizations.</li>
|
||||
<li><strong>All changes you make in Atlas will be reflected in GitHub, and vice versa.</strong></li>
|
||||
<li>
|
||||
<p><strong>You can use <a data-original-title="" href="http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging" title="">branches</a> in Atlas.</strong> On the project dashboard, select the branch you want to edit from the dropdown menu. (However, you cannot currently create new branches through Atlas.)</p>
|
||||
|
||||
<figure><img alt="Alt Text" class="icontentsimagesbranchespng" src="contents/images/branches.png" /> <figcaption>The branches dropdown menu shows all existing branches of your project.</figcaption></figure>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<p>Supported file types</p>
|
||||
<section data-type="sect1">
|
||||
<h1>Your Projects</h1>
|
||||
|
||||
<p>Atlas supports four different markup languages: HTML, markdown, asciidoc, and docbook. To use the Visual Editor, write your project in HTML making sure to adhere to the HTMLBook spec, or just use the Visual Editor right from the beginning (it already follows the HTMLBook rules).</p>
|
||||
<p>When you sign into Atlas, <strong>the first thing you'll see is a list of all your existing GitHub repos</strong>. If you want to edit or build from an existing project in GitHub, simply find and click the project in the list. To <strong>create a new project</strong>, click the New Project button to the right of the projects list.</p>
|
||||
|
||||
<p>What is a section?</p>
|
||||
<figure><img alt="Alt Text" class="icontentsimagesnewprojpng" src="contents/images/newproj.png" /> <figcaption>Click the New Project button in your project list to start fresh.</figcaption></figure>
|
||||
|
||||
<p>An integral part of the HTMLBook spec is the concept of sections. </p>
|
||||
<p>When you create a new project, <strong>Atlas will create a new <a href="http://en.wikipedia.org/wiki/Repository_(version_control)">repo</a> in your GitHub account</strong>, prepopulated with some skeleton files to help you get started. You can edit those files, delete them, or just ignore them completely and create brand-new files of your own.</p>
|
||||
|
||||
<p>Once you select a project or create a new one, <strong>you'll be taken to the project dashboard</strong>, where you'll see a list of all files in the project, and have access to the <a data-type="xref" href="#building_in_atlas">ebook-building tools</a>.</p>
|
||||
</section>
|
||||
|
||||
<section data-type="sect1">
|
||||
<h1>The Magic Line</h1>
|
||||
<h1>The Project Dashboard</h1>
|
||||
|
||||
<p>Hover over this paragraph of text. See that blue line that appears? That line helps you insert a new block wherever it shows up. By default, the line will insert just a plain paragraph, but once you do that, you can use the Insert... menu to change that new paragraph into a whole new section, sidebar, note, or some other book element.</p>
|
||||
<p><strong>The project dashboard is your landing page for each project.</strong> It lists all the files and folders in your repo, lets you switch branches, and gives you quick access to the build tools (more on building <a data-type="xref" href="#building_in_atlas">below</a>).</p>
|
||||
|
||||
<section data-type="sect2">
|
||||
<h2>Try It!</h2>
|
||||
<p>From the project dashboard, your next steps will likely be either to start writing or to build your project. <strong>Click a file in your Files pane at left to open it in the editor.</strong> For more about building, <a data-type="xref" href="#building_in_atlas">see below</a>.</p>
|
||||
</section>
|
||||
|
||||
<p>Follow these steps to get started using the magic line:</p>
|
||||
<section data-type="sect1">
|
||||
<h1>Writing and Editing</h1>
|
||||
|
||||
<ol>
|
||||
<li>
|
||||
<p>Hover over the above paragraph and click the arrow at the right of the magic blue line. </p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Now go to the insert menu, and choose "Section".</p>
|
||||
<p><strong>The Atlas editor has <a data-original-title="" data-type="xref" href="#editingenvironments" title="">two writing modes</a></strong>: the Visual Editor and the Code Editor. The Visual Editor is an online authoring environment similar to a word processor, with a formatting toolbar for tagging and styling your content. Documents created in the Visual Editor are stored as <a href="http://en.wikipedia.org/wiki/HTML5">HTML5</a>. The Code Editor allows you to view and edit the underlying HTML5 markup for your document. You can toggle back and forth between the Visual and Code Editors, and changes you make in either mode will immediately be reflected in the other.</p>
|
||||
|
||||
<p>Atlas inserts a new, nested section at the correct level. For example, if you are currently within a Section 1 block, Atlas will insert a Section 2.</p>
|
||||
</li>
|
||||
</ol>
|
||||
<p>While <strong>HTML5 is the default markup language for Atlas content</strong>, Atlas also supports documents written in<strong style="line-height: 1.5em;"> <a data-original-title="" data-type="xref" href="#markdownref" title="">Markdown</a>, <a href="http://www.methods.co.nz/asciidoc/">AsciiDoc</a>, and <a href="http://www.docbook.org/">DocBook XML</a></strong><span style="line-height: 1.5em;">. All three of these formats can be edited using the Code Editor.</span></p>
|
||||
|
||||
<p>In both writing modes, you can <strong>navigate among your files using the Files menu</strong> to the left of the screen, <strong>create and delete files</strong> <strong>and folders</strong>,<strong> <a data-original-title="" data-type="xref" href="#addingimages" title="">upload images</a></strong>, <strong>save your project</strong> (top-right button in the editor, or use the keyboard shortcut ⌘-s/Ctrl+s) and even attach a <strong>custom commit message</strong> to each save (hover over the Save button to open the commit message dialog box).</p>
|
||||
</section>
|
||||
|
||||
<section data-type="sect1">
|
||||
<h1>Creating a New File</h1>
|
||||
|
||||
<p>To create a new file, open the editor (by clicking an existing file), open the Files menu, and click the New File button at bottom left. Give your file a name, and hit Enter. </p>
|
||||
|
||||
<p>The Insert... menu gives you different options depending on where you add the new paragraph. For example, if you've used the magic line to add a new paragraph inside a sidebar, you won't be allowed to insert a section (in the HTMLBook spec, sections are only allowed to be used as high-level container elements).</p>
|
||||
<p>You can also organize your files into folders. To add a folder, click the New Folder button (next to the New File button). You can then click the folder name in the Files menu to open the folder and create new files within it.</p>
|
||||
|
||||
<div data-type="warning">
|
||||
<h1>Warning</h1>
|
||||
|
||||
<p>Sometimes the magic line won't appear after the last element in a file (section, paragraph, it doesn't matter what). To get around this, insert a new paragraph at the very end of the file. The magic line should then appear.<span style="line-height: 1.5em;"> </span></p>
|
||||
<p>You can't currently organize your files within Atlas. If you want to move existing files into a folder, you need to do that outside of Atlas using git.</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section data-type="sect1" id="building_in_atlas">
|
||||
<h1>Building</h1>
|
||||
|
||||
<p>When you're finished writing, it's time to build your project so you can share it with the world. <strong>Atlas lets you export your project in <a data-original-title="" data-type="xref" href="#outputformats" title="">four different formats</a></strong>: <a data-original-title="" data-type="xref" href="#formatspdf" title="">PDF</a>, <a data-original-title="" data-type="xref" href="#formatsepub" title="">EPUB</a>, <a data-original-title="" data-type="xref" href="#formatsmobi" title="">MOBI</a>, and <a data-original-title="" data-type="xref" href="#formatshtml" title="">HTML website</a>.</p>
|
||||
|
||||
<p>The first time you build, you'll need to choose what formats to build, and what files and settings you want to apply to each format. <strong>Click Build Settings</strong> on the project dashboard to go to the Build Settings page.</p>
|
||||
|
||||
<p>Every format has <a data-type="xref" href="#building">a few different options</a> you can choose. Two options that are common for all formats are:</p>
|
||||
|
||||
<ul>
|
||||
<li>Create a<strong> table of contents</strong> in your built project, based on your section headings. <a data-type="xref" href="#toc">Learn more here</a>.</li>
|
||||
<li>Collect all index tags you've added and create an <strong>alphabetical index</strong> in your built project. <a data-type="xref" href="#index" title="">Learn more here</a>.</li>
|
||||
</ul>
|
||||
|
||||
<p>Choose a theme for your project (more on that next). Then at the bottom of the Build Settings page, <strong>choose which files to add to the build</strong>, drag the files into the correct order, and then start the build. If the build is successful, you'll get a link to download the file. If it fails, you'll get information about what went wrong (the usual culprit is markup errors).</p>
|
||||
|
||||
<p>For subsequent builds, you can <strong>use the Quick Build tools from your project dashboard</strong>. Choose the formats you want to build, and Atlas will automatically use the same settings you initially chose on the Build Settings page.</p>
|
||||
|
||||
<figure><img alt="Alt Text" class="icontentsimagesquickbuildspng" src="contents/images/quickbuilds.png" /> <figcaption>The Builds menu on the project dashboard allows you to quickly trigger a build using your previously chosen settings.</figcaption></figure>
|
||||
</section>
|
||||
|
||||
<p>Using the Insert... menu</p>
|
||||
<section data-type="sect1">
|
||||
<h1>Themes and Design</h1>
|
||||
|
||||
<p>The toolbar</p>
|
||||
<p>All of the Atlas output formats (PDF, EPUB, MOBI, and HTML) are powered by <a href="http://en.wikipedia.org/wiki/Cascading_Style_Sheets">CSS</a>, the standard styling language for the Web. You can write <a data-original-title="" data-type="xref" href="#cssthemes" title="">an entirely new theme using CSS</a>, that can be used for multiple projects, by multiple people, or you can just add <a data-original-title="" data-type="xref" href="#csscustomizations" title="">CSS customizations</a> for your specific project.</p>
|
||||
|
||||
<p>Paste From...</p>
|
||||
<p><strong>To apply a theme to your project</strong>, choose one of the default themes on the Build Settings page, or add a link to your own custom theme.</p>
|
||||
|
||||
<p>TOC</p>
|
||||
<figure><img alt="Alt Text" class="icontentsimagesthemepng" src="contents/images/theme.png" /> <figcaption>Add a design to your project on the Build Settings page.</figcaption></figure>
|
||||
</section>
|
||||
|
||||
<p>Using the book skeleton</p>
|
||||
<section data-type="sect1">
|
||||
<h1>Building Locally with the API</h1>
|
||||
|
||||
<p>Atlas gives you the option to <strong>build locally on the command line</strong>, <a data-type="xref" href="#atlas-api">using our API</a>. (Note that you'll still need an internet connection for this to work.) This is great if you prefer to work locally using your own text editor but still want to see the final output.</p>
|
||||
</section>
|
||||
|
||||
<section data-type="sect1">
|
||||
<h1>Finding Help</h1>
|
||||
|
||||
<p>For more details on any of the above topics, or for more advanced information, <strong><a data-original-title="" href="http://atlasdocs.oreilly.com/" title="">check out the Atlas documentation</a></strong>. If you’re stuck, have specific questions about the app, or just general ideas for improvement, you can contact the Atlas team at <a data-original-title="" href="mailto:atlas@oreilly.com?subject=Atlas%20Feedback" title="">atlas@oreilly.com</a>.</p>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
Loading…
Reference in new issue