HPCE/gitea-pages
0
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Activity

updating getting started instructions

Browse Source
This commit is contained in:
Tom Johnson
2015-04-21 09:50:28 -07:00
parent b8f588185a
commit e7fce15f70
2 changed files with 201 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
.idea/workspace.xml generated
View File

@ -143,12 +143,45 @@
<favorites_list name="resolve" />
</component>
<component name="FileEditorManager">
<leaf />
<leaf>
<file leaf-file-name="getting_started.md" pinned="false" current-in-tab="true">
<entry file="file://$PROJECT_DIR$/pages/overview/getting_started.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.12295082">
<caret line="35" column="0" selection-start-line="35" selection-start-column="0" selection-end-line="35" selection-end-column="0" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
</file>
<file leaf-file-name="sidebar.yml" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/_data/sidebar.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="216" column="0" selection-start-line="216" selection-start-column="0" selection-end-line="216" selection-end-column="0" />
<folding />
</state>
</provider>
</entry>
</file>
<file leaf-file-name="linkrefs.html" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/_includes/linkrefs.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-15.0">
<caret line="25" column="106" selection-start-line="25" selection-start-column="106" selection-end-line="25" selection-end-column="106" />
<folding />
</state>
</provider>
</entry>
</file>
</leaf>
</component>
<component name="IdeDocumentHistory">
<option name="CHANGED_PATHS">
<list>
<option value="$PROJECT_DIR$/pdf_customer.sh" />
<option value="$PROJECT_DIR$/prince-file-list.txt" />
<option value="$PROJECT_DIR$/_data/glossary.yml" />
<option value="$PROJECT_DIR$/pages/endpoints/endpoints_overview.md" />
@ -199,6 +232,7 @@
<option value="$PROJECT_DIR$/_data/topnav_fe.yml" />
<option value="$PROJECT_DIR$/_includes/sidebar.html" />
<option value="$PROJECT_DIR$/_includes/topnav.html" />
<option value="$PROJECT_DIR$/pages/overview/getting_started.md" />
</list>
</option>
</component>
@ -210,9 +244,10 @@
<order />
</component>
<component name="ProjectFrameBounds">
<option name="y" value="23" />
<option name="width" value="1280" />
<option name="height" value="733" />
<option name="x" value="867" />
<option name="y" value="177" />
<option name="width" value="1323" />
<option name="height" value="1149" />
</component>
<component name="ProjectLevelVcsManager" settingsEditedManually="false">
<OptionsSetting value="true" id="Add" />
@ -237,7 +272,6 @@
<sortByType />
</navigator>
<panes>
<pane id="Scratches" />
<pane id="Scope" />
<pane id="ProjectPane">
<subPane>
@ -247,8 +281,97 @@
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.ProjectViewProjectNode" />
</PATH_ELEMENT>
</PATH>
<PATH>
<PATH_ELEMENT>
<option name="myItemId" value="resolve" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.ProjectViewProjectNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="documentation-theme-jekyll" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
</PATH>
<PATH>
<PATH_ELEMENT>
<option name="myItemId" value="resolve" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.ProjectViewProjectNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="documentation-theme-jekyll" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="pages" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
</PATH>
<PATH>
<PATH_ELEMENT>
<option name="myItemId" value="resolve" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.ProjectViewProjectNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="documentation-theme-jekyll" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="pages" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="overview" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
</PATH>
<PATH>
<PATH_ELEMENT>
<option name="myItemId" value="resolve" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.ProjectViewProjectNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="documentation-theme-jekyll" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="pages" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="formatting" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
</PATH>
<PATH>
<PATH_ELEMENT>
<option name="myItemId" value="resolve" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.ProjectViewProjectNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="documentation-theme-jekyll" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="_includes" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
</PATH>
<PATH>
<PATH_ELEMENT>
<option name="myItemId" value="resolve" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.ProjectViewProjectNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="documentation-theme-jekyll" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="_data" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
</PATH>
</subPane>
</pane>
<pane id="Scratches" />
</panes>
</component>
<component name="PropertiesComponent">
@ -339,16 +462,16 @@
<servers />
</component>
<component name="ToolWindowManager">
<frame x="0" y="23" width="1280" height="733" extended-state="0" />
<editor active="false" />
<frame x="867" y="177" width="1323" height="1149" extended-state="0" />
<editor active="true" />
<layout>
<window_info id="Project" active="false" anchor="left" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="true" weight="0.1985703" sideWeight="0.5" order="0" side_tool="false" content_ui="combo" />
<window_info id="Project" active="false" anchor="left" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="true" weight="0.1920123" sideWeight="0.5" order="0" side_tool="false" content_ui="combo" />
<window_info id="TODO" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.33" sideWeight="0.5" order="6" side_tool="false" content_ui="tabs" />
<window_info id="Event Log" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.32928678" sideWeight="0.5" order="7" side_tool="true" content_ui="tabs" />
<window_info id="Application Servers" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.33" sideWeight="0.5" order="10" side_tool="false" content_ui="tabs" />
<window_info id="Version Control" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.33" sideWeight="0.5" order="8" side_tool="false" content_ui="tabs" />
<window_info id="Structure" active="false" anchor="left" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.24979983" sideWeight="0.5" order="1" side_tool="false" content_ui="tabs" />
<window_info id="Terminal" active="true" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="true" weight="0.10696921" sideWeight="0.5" order="9" side_tool="false" content_ui="tabs" />
<window_info id="Terminal" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.06849315" sideWeight="0.5" order="9" side_tool="false" content_ui="tabs" />
<window_info id="Favorites" active="false" anchor="left" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.33" sideWeight="0.5" order="2" side_tool="true" content_ui="tabs" />
<window_info id="Cvs" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.25" sideWeight="0.5" order="4" side_tool="false" content_ui="tabs" />
<window_info id="Message" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.33" sideWeight="0.5" order="0" side_tool="false" content_ui="tabs" />
@ -386,7 +509,6 @@
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="0" column="0" selection-start-line="0" selection-start-column="0" selection-end-line="0" selection-end-column="0" />
<folding />
</state>
</provider>
</entry>
@ -434,13 +556,6 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_includes/linkrefs.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.7121535">
<caret line="130" column="21" selection-start-line="130" selection-start-column="21" selection-end-line="130" selection-end-column="21" />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/index.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.78125">
@ -472,35 +587,10 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_includes/reuse/endpoint_descriptions.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="5" column="0" selection-start-line="5" selection-start-column="0" selection-end-line="5" selection-end-column="0" />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/push.sh">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.026833631">
<caret line="2" column="76" selection-start-line="2" selection-start-column="76" selection-end-line="2" selection-end-column="76" />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_data/sidebar.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="9.694073">
<caret line="338" column="25" selection-start-line="338" selection-start-column="25" selection-end-line="338" selection-end-column="25" />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_includes/topnav.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.66132265">
<caret line="59" column="12" selection-start-line="59" selection-start-column="12" selection-end-line="59" selection-end-column="12" />
<folding />
</state>
</provider>
</entry>
@ -512,5 +602,54 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/formatting/links.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-0.13729508">
<caret line="0" column="0" selection-start-line="0" selection-start-column="0" selection-end-line="0" selection-end-column="0" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/formatting/alerts.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="0" column="0" selection-start-line="0" selection-start-column="0" selection-end-line="0" selection-end-column="0" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_includes/linkrefs.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-15.0">
<caret line="25" column="106" selection-start-line="25" selection-start-column="106" selection-end-line="25" selection-end-column="106" />
<folding />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_data/sidebar.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="216" column="0" selection-start-line="216" selection-start-column="0" selection-end-line="216" selection-end-column="0" />
<folding />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/overview/getting_started.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.12295082">
<caret line="35" column="0" selection-start-line="35" selection-start-column="0" selection-end-line="35" selection-end-column="0" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
</component>
</project>

36
pages/overview/getting_started.md
View File

@ -4,15 +4,15 @@ permalink: /getting_started/
tags: getting-started
audience: writer, designer
---
{% include linkrefs.html %}
## Prerequisites
* Mac computer (recommended). If you have a PC, you need to see [Jekyll on Windows](http://jekyllrb.com/docs/windows/). Make sure you can get Jekyll working on Windows before proceeding.
* Ruby. This should already be installed. Type `which ruby` to confirm.
* [Ruby](https://www.ruby-lang.org/en/). This should already be installed. Type `which ruby` to confirm.
* [Rubygems](https://rubygems.org/pages/download). This is a package manager for Ruby (gems).
* Jekyllrb. To install: `gem install jekyll`
* * [Git](http://git-scm.com/download/mac). Type `which git` to see if you already have it installed.
* text editor (some examples: Sublime Text, Atom, WebStorm, Emacs)
* [Jekyllrb](http://jekyllrb.com/). To install: `gem install jekyll`
* [Git](http://git-scm.com/download/mac). Type `which git` to see if you already have it installed.
* Text editor (some examples: Sublime Text, Atom, WebStorm)
* [iTerm](http://iterm.sourceforge.net/) - optional but recommended instead of Terminal.
{{warning}} These instructions are designed for users on Macs. Jekyllrb supposedly works on Windows but is not officially supported on that platform. See <a href="Jekyll on Windows">http://jekyllrb.com/docs/windows/</a> for more details. {{end}}
@ -54,26 +54,28 @@ cd acme
2. Once you're inside the folder for your project (for example, acme), type `git clone https://github.com/tomjohnson1492/documentation-theme-jekyll.git .` (The ` .` means to clone the github repo into the current directory. Make sure the directory is empty before cloning the theme in there.)
3. In your new project folder, remove the .git folder, because no doubt you'll be customizing this project's content and committing it to another revision control repository.
4. In the theme's configs directory, rename config_writer.yml to config_[your audience].yml and customize all the values inside that file based on the instructions in that file. Do the same with config_designer.yml and continue to clone the config file for other audiences.
4. In the theme's configs directory, rename config_writer.yml to config_[your audience].yml and customize all the values inside that file based on the instructions in that file. Do the same with config_designer.yml and continue to clone and customize the config file for other audiences.
In this theme, each output requires an individual config file. Each print output requires a separate config file. If you have 10 audiences and you want both web and PDF outputs for each audience, then you'll have 20 config files in this directory.
In this theme, each output requires an individual config file. Each print output requires a separate config file. If you have 10 audiences and you want both web and PDF outputs for each audience, then you'll have 20 config files in this directory.
5. In the _includes directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace `writer` with your audience, and `designer` with another audience.)
6. Remove the content inside the pages folder, and then add your own pages in this pages folder. (Using subfolders and sub-subfolders inside pages is all right -- you don't have to worry about folder paths in links.)
5. In the _includes directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace `writer` with your audience, and `designer` with another audience.) The conditions.html file is used to apply different audience requirements to the sidebar and other files.
6. Remove the content inside the pages folder, and then add your own pages in this pages folder. (Using subfolders and sub-subfolders inside the pages folder is all right -- you don't have to worry about folder paths in links.)
7. Inside _data, open sidebar.yml and topnav.yml and customize the navigation. (Don't mess up the spacing or change any of the YML level names or the site or sidebar won't build.)
8. In the root directory, rename build_writer.sh to build_[your audience].sh (same with build_designer.sh for additional outputs). In the files' contents, change the build parameters to point to the configuration file and destination/output directory that you want. The `--config` parameter specifies the directory where the build reads the configuration file, and the `-o` parameter specifies the directory where the PDF is built.
8. In the root directory, rename build_writer.sh to build_[your audience].sh (same with build_designer.sh for additional outputs). In the files' contents, change the build parameters to point to the configuration file and output directory that you want.
The `--config` parameter specifies the directory where the build reads the configuration file, and the `-o` parameter specifies the directory where the PDF is built.)
{{note}} See <a href="{{ /create_pdf | prepend: site.baseurl }}">Creating a PDF</a> for more details on creating PDF documents. You will need to set up Prince in order for the PDF build to work. {{end}}
{{note}} For more information on setting up PDF builds, see {{create_pdf}}. You will need to set up Prince in order for the PDF build to work. {{end}}
9. In the root directory, customize the index.md file. This file will be the homepage for each of your projects. Use conditional tags to change the content for different builds of your site. See {{conditional_logic}} for more information.
10. In the _includes folder, open linkrefs.html and add capture tags for all the pages in your site following the sample format shown. This will make it easy to link to each of the topics. (Don't remove the capture tags for the alerts and callouts.)
11. In the _includes folder, open footer.html and customize the content. If you have different footers for different outputs, use conditional tags.
9. In the root directory, customize the index.md file. This file will be the homepage for all of your projects. Use conditional tags (for example, `if site.audience == "writer" ...`) to change the content for different builds of your site. See {{conditional_logic}} for more information.
10. In the _includes folder, open linkrefs.html and add capture tags for all the pages in your site following the sample format shown. This will make it easy to link to each of the topics. (Don't remove the capture tags for the alerts and callouts.)
11. For each of your pages where you want to insert a link, note, or callout, add {%raw%}`{% include linkrefs.html %}`{%endraw%} directly below the frontmatter.
12. In the _includes folder, open footer.html and customize the content. If you have different footers for different outputs, use conditional tags as you did on index.md.
12. In the layouts folder, open page.html and customize the values in the `site.show_audience_label` section. These are labels that appear on the page based on the audience attributes in the frontmatter for that page. If you want these shown, make sure you have `true` set for the `site.show_audience_label` property in your config file.
11. Build your site with `. build_writer.sh` and preview it at the URL provided.
11. Build your site with `. build_acme.sh` and preview it at the URL provided.
If you have 10 different outputs, you'll have 10 separate configuration files in your configs directory, and probably 10 different shell scripts containing build arguments for each configuration.
{{callout_info}}If you have multiple outputs, you probably don't want to use Github Pages to publish your site, since Github Pages looks for a _config.yml file in the root directory and uses that to build a site in the gh-pages branch of your repository. You can't instruct Github pages to look in another directory for the right configuration file. Instead, you'll probably have a better experience publishing to a Amazon Web Services S3 bucket or some other web host.{{end}}
{{callout_info}}<b>Publishing to web hosts:</b> If you have multiple outputs, you probably don't want to use Github Pages to publish your site, since Github Pages looks for a _config.yml file in the root directory and uses that to build a site in the gh-pages branch of your repository. You can't instruct Github pages to look in another directory for the right configuration file. Instead, you'll probably have a better experience publishing to a Amazon Web Services S3 bucket or some other web host.{{end}}
## Questions