I am generating documentation project using ReadThedocs (mkdocs). But It's generating documentation project for the .md files which are placed in docs directory. My requirement is, I want to build documentation project for every .md file placed anywhere in the github repository.
How to achieve this?
You need to specify in the Mkdocs configuration (mkdocs.yml) the location of your documentation directory to be the current directory '.'.
Example:
site_name: My Documentation Project
docs_dir: '.'
By default, the Mkdocs looks in a subdirectory of your project labled docs:
docs_dir
Lets you set the directory containing the documentation source markdown files. This can either be a relative directory, in which case it is resolved relative to the directory containing you configuration file, or it can be an absolute directory path.
default: 'docs'
This is not possible in MkDocs by default. See this GitHub issue thread for rationale. There is however a plugin called mkdocs-same-dir that can be used to achieve this.
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 Jekyll-based and Github-pages-hosted site. I also have a Git Submodule that contains both YAML files and images. I would like to use it within my GitHub pages Jekyll project but I’m not sure how.
Here's example directory structure:
/assets/
/_data/
/MyGitSubmodule/yaml/
/MyGitSubmodule/images/
I’m used to putting YAML files in _data and images in /assets/. Is there a way to configure Jekyll also parse YAML files in another directory? Or copy static files from somewhere in _data during the build step? Or set up symlinks? That work with GitHub Pages?
I've tried:
Changing the data_dir setting to be the same as my /assets/ directory but I don't want to make my data files publicly accessible.
Creating a symbolic link on Windows with mklink /D but I get an error on servingC:/Ruby26-x64/lib/ruby/gems/2.6.0/gems/jekyll-4.2.2/lib/jekyll/utils.rb:141:in initialize': Is a directory # rb_sysopen - C:/Ben/personalsite2/assets/unreal/specifiers (Errno::EISDIR)`. Also ]this page seems to imply that they work on GitHub pages](https://github.com/chetabahana/symlink) but other docs for Jekyll seem to say that they are disabled in “safe mode” and GitHub pages.
Eh in the end I solved this by putting my data_dir inside /assets/ and by by using the exclude setting in config.yml to stop it from serving some of the yml files
I recently decided to generate a Github Pages website using Hugo. I wanted to keep Hugo input (configuration, themes) in the same directory as the output, for easy management. Unfortunately, Github Pages's CI complains when I try to turn public directory into a symlink into ., as well as when I create a hugo directory and make hugo/public a symlink to ... Are there any other options to keep configs and output in the same directory, bypassing that error?
I solved the problem by putting the following in my config.toml file:
publishDir = "."
As a result, I didn't need the "public" directory pointing to ..
Starting with a default installation of SilverStripe (using composer), I have the folders framework, cms, mysite, etc.
Using composer I then added some additional code, such as userforms with the command:
composer require silverstripe/userforms
This created the folder userforms in the root of my site.
However, to manage my code more easily, it would be nicer if all modules added by composer were in a subfolder together. This answer indicates how a default vendor-dir directory can be specified using the composer.json file.
There is already a vendor folder in existence (if I understand correctly, this is used by composer). Is it ok to use the vendor folder as the default vendor-dir setting, or would it be better to create a new folder instead?
Also, what do I need to do to move existing folders (such as userforms) into the appropriate sub-folder?
This behaviour is specified by type. The packages with "type": "library" will be placed into vendor folder.
This is how the framework was designed, it expects the files to be located where they are now. It uses legacy code and is unable to make use of Composer autoloading.
I don't know how to add the this into my existing project.
The only thing I learned so far was adding jar files, not those types of folders. How would I add the source to my project? Are they packages?
Steps I've done:
Download
Extract into a separate folder
I think I might be over thinking it.
If I interpret the download link right, you are downloading the sources of a lib.
If you are not already using that library, you should download this instead and add it to the project's build path. Copy it to your folder, where you have your other libs placed and add it via right click menu Build Path *-->* Add to Build Path. Afterwards you can use the classes from that library.
If you already have that lib in your project, I guess you want to attach the sources to the lib. Therefore you need to go into your project's build path and edit the jar, and configure there, where the zip file (which does not need to be extracted) with the sources is. There is a detailed description for linking sources to jar files in the eclipse documentation.
For further details on build path configuration you could read in the eclipse documentation.