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

removing the info about using bundler b/c people were getting errors and it was causing confusion unnecessarily. also made an edit to bootstrap's print media styling to allow color.

Browse Source
This commit is contained in:
Tom Johnson 2015-12-02 14:44:42 -08:00
parent e4e080c28b
commit ee12a85c6d
4 changed files with 37 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
css/bootstrap.min.css vendored
View File

File diff suppressed because one or more lines are too long

6
css/printstyles.css
View File

@ -149,8 +149,12 @@ h1 { string-set: doctitle content() }
} }
} }
.alert { .alert {
background-color: #f0f0f0 !important; background-color: #fafafa !important;
border-color: #dedede !important; border-color: #dedede !important;
color: black;
} }
pre {
background-color: #fafafa;
}

19
mydoc/mydoc_generating_pdfs.md
View File

@ -379,3 +379,22 @@ javascript content here ...
{% endraw %} {% endraw %}
For more detail about using `unless` in conditional logic, see {{site.data.mydoc.mydoc_urls.mydoc_conditional_logic.link}}. What this code means is "run this code unless this value is the case." For more detail about using `unless` in conditional logic, see {{site.data.mydoc.mydoc_urls.mydoc_conditional_logic.link}}. What this code means is "run this code unless this value is the case."
## Overriding Bootstrap Print Styles
The theme relies on Bootstrap's CSS for styling. However, for print media, Bootstrap applies the following style:
```
@media print{*,:after,:before{color:#000!important;text-shadow:none!important;background:0 0!important;-webkit-box-shadow:none!important;box-shadow:none!important}
```
This is minified, but basically the `*` (asterisk) means select all, and applied the color #000 (black). As a result, the Bootstrap style strips out all color from the PDF (for Bootstrap elements).
This is problematic for code snippets that have syntax highlighting. I decided to remove this de-coloring from the print output. I commented out the Bootstrap style:
```
@media print{*,:after,:before{/*color:#000!important;*/text-shadow:none!important;/*background:0 0!important*/;-webkit-box-shadow:none!important;box-shadow:none!important}
```
If you update Bootrap, make sure you make this edit. (Sorry, admittedly I couldn't figure out how to simply overwrite the `*` selector with a later style.)
I did, however, remove the color from the alerts and lighten the background shading for `pre` elements. The printstyles.css has this setting.

37
mydoc/mydoc_getting_started.md
View File

@ -16,7 +16,6 @@ Before you start installing the theme, make sure you have all of these prerequis
* **Mac computer**. If you have a Windows machine, make sure you can get a vanilla Jekyll site working before proceeding. You'll probably need Ruby and Ruby Dev Kit installed first. Also note that the shell scripts (.sh files) in this theme for automating the builds work only on a Mac. To run them on Windows, you need to convert them to BAT. * **Mac computer**. If you have a Windows machine, make sure you can get a vanilla Jekyll site working before proceeding. You'll probably need Ruby and Ruby Dev Kit installed first. Also note that the shell scripts (.sh files) in this theme for automating the builds work only on a Mac. To run them on Windows, you need to convert them to BAT.
* **[Ruby](https://www.ruby-lang.org/en/)**. On a Mac, this should already be installed. Open your Terminal and type `which ruby` to confirm. * **[Ruby](https://www.ruby-lang.org/en/)**. On a Mac, this should already be installed. Open your Terminal and type `which ruby` to confirm.
* **[Rubygems](https://rubygems.org/pages/download)**. This is a package manager for Ruby. Type `which gem` to confirm. * **[Rubygems](https://rubygems.org/pages/download)**. This is a package manager for Ruby. Type `which gem` to confirm.
* **[Bundler](http://bundler.io/)**. Bundler is Ruby gem that automatically downloads Ruby gems that you need for a specific project.
* **Text editor**: My recommendations is WebStorm (or IntelliJ). You can use another text editor. However, there are certain shortcuts and efficiencies in WebStorm (such as using Find and Replace across the project, or Markdown syntax highlighting) that I'll be noting in this documentation. * **Text editor**: My recommendations is WebStorm (or IntelliJ). You can use another text editor. However, there are certain shortcuts and efficiencies in WebStorm (such as using Find and Replace across the project, or Markdown syntax highlighting) that I'll be noting in this documentation.
## Build the default project ## Build the default project
@ -27,7 +26,7 @@ Before you start customizing the theme, make sure you can build the theme with t
You can either download the theme files directly by clicking the **Download Zip** button on the right of the repo, or use git to clone the repository to your local machine. You can either download the theme files directly by clicking the **Download Zip** button on the right of the repo, or use git to clone the repository to your local machine.
5. After downloading the theme, note some unique aspects of the file structure: 2. After downloading the theme, note some unique aspects of the file structure:
* Although there's a \_config.yml file in the root directory, it's there only so that Github Pages will build the theme. Because the theme is set up for single sourcing, there's a separate configuration file for each unique output you're building. * Although there's a \_config.yml file in the root directory, it's there only so that Github Pages will build the theme. Because the theme is set up for single sourcing, there's a separate configuration file for each unique output you're building.
* All the configuration files are stored in the configs directory. Each configuration file has a different preview port. If you want, you can build and preview all your outputs simultaneously in different preview servers. * All the configuration files are stored in the configs directory. Each configuration file has a different preview port. If you want, you can build and preview all your outputs simultaneously in different preview servers.
* Each configuration file specifies a different project and potentially a different audience, product, platform, and version. By setting unique values for these properties in the includes/custom/conditions.html file, you determine how the sidebar and top navigation get constructed. * Each configuration file specifies a different project and potentially a different audience, product, platform, and version. By setting unique values for these properties in the includes/custom/conditions.html file, you determine how the sidebar and top navigation get constructed.
@ -40,31 +39,15 @@ Before you start customizing the theme, make sure you can build the theme with t
In reality, both of these outputs are pretty much the same. I mainly incorporated two outputs here mainly to demonstrate how the single sourcing works. In reality, both of these outputs are pretty much the same. I mainly incorporated two outputs here mainly to demonstrate how the single sourcing works.
3. Install Bundler: 3. Unless you're planning to publish on Github Pages, you can delete the Gemfile. The Gemfile is only in this project to allow publishing on Github Pages.
``` The theme is not using a Gemfile to manage project dependencies. Although theoretically the Gemfile should make things easier, I've found that it tends to give users more errors than they need. Add to this the incompatibility of Github Pages with Jekyll 3.0 and the Gemfile becomes even more problematic.
gem install bundler
```
Bundler is a utility for retrieving all of the project's dependencies automatically. This utility helps you avoid errors in building the project. 4. Install the [Jekyll](https://rubygems.org/gems/jekyll), [redcarpet](https://rubygems.org/gems/redcarpet), and [pygments](https://rubygems.org/gems/pygments.rb) gems.
Bundler looks at the gems (Ruby plugins) in a project's gemfile and then gets all of the gems that depend on those gems. This way you don't end up with incompatible gems. These gems are the only ones the project uses. Go to the [Rubygems site](https://rubygems.org) for each of these gems (based on the links above). In the right column, click the "INSTALL" command and paste the copied command into your terminal. If your computer gives you permissions errors, add `sudo` before the command.
Since I'm publishing this project on Github Pages, there are some specific gem dependencies. The 2.5.3 github-pages gem has dependencies on jekyll 2.4.0, pygments.rb 0.6.3, and redcarpet 3.3.2 (you can see this after running `bundle install`). If you're not publishing on Github Pages and you want to run Jekyll 3.0.1 (the latest), browse to the jekyll-documentation-theme folder and type `open Gemfile`. Replace the contents of the Gemfile with the following:
```
source 'https://rubygems.org'
gem 'jekyll', '~> 3.0'
gem 'redcarpet', '~> 3.3', '>= 3.3.3'
gem 'pygments.rb', '~> 0.6.3'
```
5. In a terminal, browse to the documentation-theme-jekyll directory and type the following:
```
bundle install
```
5. In your terminal, browse to the documentation-theme-jekyll folder that you downloaded.
6. Build the writer's output: 6. Build the writer's output:
``` ```
@ -75,8 +58,8 @@ Before you start customizing the theme, make sure you can build the theme with t
Open a new tab in your browser and preview the site at the preview URL shown. Open a new tab in your browser and preview the site at the preview URL shown.
4. Press **Ctrl+C** in Terminal to shut down the writer's preview server. 7. Press **Ctrl+C** in Terminal to shut down the writer's preview server.
5. Build the designers output: 8. Build the designers output:
``` ```
jekyll serve -config configs/mydoc/config_designers.yml jekyll serve -config configs/mydoc/config_designers.yml
@ -84,8 +67,8 @@ Before you start customizing the theme, make sure you can build the theme with t
Open a new tab in your browser and preview the site at the preview URL shown. Notice how the themes differ (designers is blue, writers is green). Open a new tab in your browser and preview the site at the preview URL shown. Notice how the themes differ (designers is blue, writers is green).
5. Press **Ctrl+C** in Terminal to shut down the designer's preview server. 9. Press **Ctrl+C** in Terminal to shut down the designer's preview server.
6. Build both themes by running the following command: 10. Build both themes by running the following command:
``` ```
. mydoc_3_multibuild_web.sh . mydoc_3_multibuild_web.sh