All tutorials I've seen so far describe how to create single page sites or just several bundles. Here is an example of a simple website navigation:
example.com/home
example.com/about
example.com/services
example.com/services/marketing
example.com/services/development
example.com/contact
Is it possible to build such a site with bem-tools, bemjson, bemhtml but without any serverside tech like node.js or php?
The build should include only a directory with final .html, .css, .js files and images per page and should be hosted on a static file hosting like Amazon S3. It should also be an oldschool static website, not a single page ajax site.
Is there any easy to use solution for this use case or should one create her own build process to collect the files from the bundle directories?
Good question, and the answer is - yes, you can :)
First of all, you need to clone project-stub repo and install dependencies:
git clone git#github.com:bem/project-stub.git
cd project-stub
npm i
./node_modules/.bin/bem make libs
Now you have configured project stub to develop site with bem-tools.
Page index is included.
Let's create page about:
./node_modules/.bin/bem create -b about -l desktop.bundles/
This command creates file desktop.bundles/about/about.bemjson, which represents your page in BEM terms.
You can see this page when you run
./node_modules/.bin/bem server
and open http://localhost:8080/desktop.bundles/about/about.html in browser.
Read more: http://bem.info/libs/bem-core/1.0.0/bemhtml/reference/, "The Input Data: BEMJSON" chapter.
To get final css with rigth image path's, you need to install cssrb package:
sudo npm i cssrb -g
And to get final build directory, you need to put bem-static-build.sh file in root of your project and run it:
wget https://raw.github.com/alexbaumgertner/bem-static-build/master/bem-static-build.sh
sh bem-static-build.sh
After builder process ended, you can find static site in desktop.bundles/merged/build folder:
NB:
If you have content images on your page, you must put them into desktop.bundles/merged/img folder and make symlinks to all pages folders:
ln -s $(pwd)/desktop.bundles/merged/img $(pwd)/desktop.bundles/index/img
ln -s $(pwd)/desktop.bundles/merged/img $(pwd)/desktop.bundles/about/img
and etc for all pages. This actions are needed because bem server shows a page relative to its folder and with symlink you can write image src in about.bemjson and all pages like this:
{
block: 'user',
content: [
{
elem: 'avatar',
tag: 'img',
attrs: {
src: 'img/dypsilon.png' // relative way
}
}
]
}
and it should work!
Any questions are welcome!
Related
I'm a total newbie when it comes to Jekyll, and have encountered a big problem. I'm probably doing something wrong or missing something, but what?
I find it very confusing trying to install the "Agency Jekyll Theme" which is the first theme I'm trying out. Mostly because there are several ways to do it, the commands don't add up and there is a lot of "you can do this" embedded into what you actually have to do to install it.
These are the guides I've been following:
https://jekyllrb.com/docs/step-by-step/01-setup/
https://www.rubydoc.info/gems/jekyll-agency/1.2.0
http://jekyllthemes.org/themes/agency/
Basically, I've tried all the 3 possible ways to install it without success.
I'm running on Windows.
My problem:
jekyll serve (ran in my site folder) creates a _site folder and content in the subfolders css, img and js. Nothing else is created, not index.html, and other files needed directly under _site folder.
In my site root folder, there are only _config.yml and Gemfile, after completing the initial steps.
There seems to be a problem with actually downloading the full theme into my root folder. When I manually download the agency-jekyll-theme-starter-master.zip and extract the entire content in my root site folder, there is index.html, _data folder, etc. However, in the assets folder, there is only an img folder.
As a result, when I open http://localhost:4000/agency-jekyll-theme-starter/ in a browser there is only a directory listing with the folder "assets".
Where do the css folder and its content come from that generates under _site?
My workaround:
I run jekyll build so that the site in its entirety is placed under _site folder. However, with this process, the whole point of using Jekyll is lost because I have to edit the generated HTML files, CSS files, etc. To change simple stuff like renaming the page/navigation "Services" to another word I have to go through the HTML file and replace all occurrences
My successful attempt to reproduce your issue:
I tried this method from http://jekyllthemes.org/themes/agency/
Using the Starter Template
This is the fastest and easiest way to get up and running on GitHub Pages. Simply generate your own repository by clicking here, then replace the sample content with your own and configure for your needs.
The starter template (that is also linked on the page above) allowed me to start a code space and commit the repo content into my new branch.
I could reproduce your problem, there were no styles when running jekyll serve.
The reason for the issue:
The problem is the baseurl in the _config.yml file. It points to a relative path that does not exist in your repository. Your baseurl / path is "", because you run your server from the root folder, most probably both locally and later remotely using GitHub pages.
The solution for the issue:
In the _config.yml file in your repo, change this one line
from
baseurl: "/agency-jekyll-theme-starter" # the subpath of your site, e.g. /blog
to
baseurl: "" # the subpath of your site, e.g. /blog
Check out https://github.com/cadamini/jekyll-agency-test if you like.
I hope this was understandable and helpful and that you can solve your issue with these instructions. Don't hesitate to comment for further clarification.
I have a bunch of static files (basically favicons, apple-site-icons, etc) that I want to be at the root of _site when it's built. Currently they're just sitting at the root of my main code folder (along with _posts, _scss, _layouts, etc). It builds fine but it would be nice to move them into a subdirectory so the main directory isn't cluttered up (it's an OCD thing).
Is there any folder where I can put these items so they automatically copy to the root of _site when I build? I know I can write a script to do this and trigger it after the build, and there's probably an extension I could lean on, but I'm looking for a solution that just automatically moves them when I run jekyll build for simplicity.
NBD if I can't do it, just curious because I'm kind of a neat freak.
Thanks!
Jekyll allows you to do exactly that using permalinks.
Permalinks are the output path for your pages, posts, or collections. They allow you to structure the directories of your source code different from the directories in your output.
A simple example extracted from the official page is a case where you have /my-pages/about-me.html with the front matter as follows:
---
permalink: /about/
---
This way you specify the output url. In this example, you could access it in local with localhost:4000/about/
The source option. You can specify this in your _config.yml or as a command line option (https://jekyllrb.com/docs/configuration/options/). How you set this has slightly different requirements/implications.
First, move everything that belongs to the Jekyll site into a folder (e.g. "src").
Then set one of these up (assuming you have a Gemfile):
Command line option with root Gemfile:
Keep Gemfile in the root folder
Run bundle install
Run bundle exec jekyll serve --source src
Command line option with nested Gemfile:
Run BUNDLE_GEMFILE=src/Gemfile bundle install
Run BUNDLE_GEMFILE=src/Gemfile bundle exec jekyll serve --source src
Config file option:
Keep Gemfile and _config.yml in the root folder
Add source: src somewhere in your _config.yml
Run bundle install
Run bundle exec jekyll serve
Each solution here might work better with other external services building your site. There are likely other ways to set this up, but this should get you started.
GitLab doesn't render HTML for me, but just display the source code:
Background: I used sphinx to generate the HTML and tried to show the doc at GitLab.
I looked at other projects' repositories, such as pandas, sphinx. They only have .rts files in the repository, and not HTML files. I guess they generate HTML for their websites but don't upload to Git.
I don't have a website and want to show doc at GitLab. Is there a way to do that? Or do I have to generate other formats (other than HTML, e.g. PDF) instead?
First of all, Git and products like GitLab and GitHub are different things. Git doesn't ever render anything; it's a version control system. It doesn't have a web interface.
Secondly, GitLab's core product isn't supposed to render anything. It's not a web host, it's a tool for hosting, sharing, and managing Git repositories. However you might want to try GitLab Pages:
GitLab Pages is a feature that allows you to publish static websites directly from a repository in GitLab.
You can use it either for personal or business websites, such as portfolios, documentation, manifestos, and business presentations. You can also attribute any license to your content.
Pages is available for free for all GitLab.com users as well as for self-managed instances (GitLab Core, Starter, Premium, and Ultimate).
GitLab Pages will publish content from the public/ directory of your repository, so you should move your files there. You will also need a .gitlab-ci.yml file in the root of your repository containing something like
image: alpine:latest
pages:
stage: deploy
script:
- echo 'Nothing to do...'
artifacts:
paths:
- public
only:
- master
(taken from the sample repository). Add that file, then commit and push. After deployment is complete, your site should be available at https://youruser.gitlab.io/yourproject.
Note that GitHub has a similar product (that works differently).
Finally,
I looked at other projects' repositories, such as pandas, sphinx. They only have .rts files in the repository, and not HTML files. I guess they generate HTML for their websites but don't upload to Git.
it's very likely that the reStructured Text files are the only source that exists, and that HTML is generated from them automatically. Sphinx this format by default. If you're interested in working from another format like Markdown or reStructured Text you may want to explore GitLab Pages' support for static site generators.
There is a super easy solution I found on this post:
Before:
https://gitlab.com/[user]/[repository]/raw/[branch]/[filename.ext]
After:
Development (throttled)
https://gl.githack.com/[user]/[repository]/raw/[branch]/[filename.ext]
Production (CDN)
https://glcdn.githack.com/[user]/[repository]/raw/[branch]/[filename.ext]
Another solution:
At the root of your repo, add a file called .gitlab-ci.yml containing the following lines:
pages:
script:
- mkdir .public
- cp -r * .public
- mv .public public
artifacts:
paths:
- public
Your file should then be available at
https://your-username.gitlab.io/project-name/filename.html
See this post for details: Gitlab: host and render HTML files
The index.html home page displays fine, however any any link will throw a 404.
The static website has folder with html in it, index link to these html with the correct path, but displays a 404.
When clicking on this link, I got a 404.
however the file is present as you can see here .
I am really banging my head on a simple html pb, which is frustrating.
I ran into this problem myself and finally discovered a simpler solution. The problem is that Jekyll ignores all files that start with _. The simple solution is to add a .nojekyll file to your docs dir.
My docs script looks like this:
"rimraf ./docs && typedoc src/ --out docs --mode modules --module commonjs --target es6 --excludePrivate && touch ./docs/.nojekyll && gh-pages -d docs -t"
touch is an npm module that creates the file and the -t flag on gh-pages is necessary to have that dot file uploaded.
Alright I though I might just answer my own question here.
Github Page doesn't allow several static HTML files.
This is not very clear to be honest on their docs, but the solution is quite simple :
Assuming your local static docs works correctly, just follow these steps :
install jekyll
gem install jekyll bundler
add a file _config.yml
in your docs or on the root of your gh-pages branch with this content:
auto: true
execute jekyll serve
And test if this works ok on the url outputed in your console
add _site in your .gitignore
push and bingo!
If you are like me using typedoc to compile typescript into nice documentation, you will run into trouble.
Because Jekyll automatically exclude from the build any files starting with _, and typedoc generates ONLY that, I wrote a simple yeoman generator that does all the replacement for you.
I'm considering Jekyll for a site I'm putting together that will be a blog with lots of images (and other larg-ish media files). It's easy enough to to make a directory for images and then link to them as needed in the posts. But, as I understand it, when the site is generated, all the image data will be duplicated into the generated _site directory that holds the static files. Each time the site is generated the _site directory is emptied, and repopulated with the static version of the site.
Is there any way to, for example, drop a symlink to the images directory inside the site directory, and then maybe have jekyll ignore it when the static files are generated?
Or is there another way to go about this that makes more sense?
Assuming you are running on an apache web server, you can setup an Alias directive to serve images from a directory outside of the normal docroot. You need access to edit the VirtualHosts config or some other ability to create aliases directives (e.g. via a control panel).
For an example of how this would work, let's say you are storing your jekyll files under a directory called "/web/jekyll". To get your images directory do the following:
Add an "_images" directory along with your basic jekyll tree. Ending up with something like:
_config.yml
_images/
_layouts/
_posts/
_site/
index.md
Update your apache config to add the Alias directive like:
Alias /images /web/jekyll/_images
Reload the apache config and run jekyll to build the site.
Since the image directory name starts with an underscore, jekyll won't push/copy it to the output _site during the build. Apache will happily serve most files from your _site directory as normal, but when it sees something like "http://jekyll/images/test.jpg", instead of looking for the file under "/web/jekyll/_site/_images/test.jpg", it'll serve it from "/web/jekyll/_images/test.jpg".
Incidentally, I like a little more separation of the source content and output content than jekyll defaults to. So, I setup my directory structure as follows:
/web/jekyll/html/
/web/jekyll/images/
/web/jekyll/source/
/web/jekyll/source/_config.yml
/web/jekyll/source/_layouts
/web/jekyll/source/_posts
/web/jekyll/source/index.md
With the following option set in _config.yml
destination: ../html
And the apache alias directive setup with:
Alias /images /web/jekyll/images
Jekyll is run in the "/web/jekyll/source" directory, but output is sent to the "/web/jekyll/html" dir. Similar to the first example, calls to "http://jekyll/images/test.jpg" are served from "/web/jekyll/images/test.jpg". This setup doesn't really make a difference from a site serving perspective. I just like the cleaner separation between the raw source files, the fully baked output files and the images which work via the alias.
Correct, the first part of the jekyll command removes everything in the destination directory. The problem with that is the symlinks must be manually created again. So next, go ahead and create a script that does this each time.
Be sure that:
exclude: [jekyll, css, img] in the _config.yml file
linux: The ";" symbol runs first, second, third.. commands.
script: A file named jekyll with executable permissions containing
jekyll;
ln -s /var/www/css /var/www/_site/css;
ln -s /var/www/img /var/www/_site/img;
Finally run (./jekyll) that program instead of jekyll.
-Dan
Make a project page for the images.
Set up directory structure
/home/git/svnpenn.github.io
/home/git/img
Run Jekyll
# We cant add the symlink until after jekyll is done. We will remove the
# site folder and wait for it to rebuild.
rm -r _site
jekyll --server &
while [ ! -f _site/index.html ]
do
sleep 1
done
ln -s ../images _site/images
Note I was using this because I thought it would help publish time on GitHub
pages. It does not. GitHub can take 1-10 minutes to publish depending on the
server.
I know this has already been answered, but I went a slightly different route. I hosted all of my images in a public directory on Dropbox and use grunt to generate a manifest of the images. It keeps my repository small because the images don't get checked in. I detailed it a while back in a blog post.